ftp.whtech.com/ftp.whtech.com.tar/ftp.whtech.com/Geneve/mdos/80column_funnelweb/psrv.txt

Text File | 2006-10-19 | 20KB | 466 lines

                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                FUNNELWEB - PROGRAM SERVICES for ASSEMBLY USAGE
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

                              Version  4.40
                             -------------


             The FUNNELWEB system is held together by a reference block
        at the top of high memory.  This has grown somewhat haphazardly
        over the years, but at this stage of the history of the TI 99/4a
        computer, plans for complete tidying up and revision have been
        shelved although almost all functional improvements, and more,
        previously intended for that grand revision have now been
        incorporated in Vn 4.40 of FUNNELWEB.

             The information and facilities available include BLWP
        vectors for a variety of services, indirect BL routine pointers,
        and various data, pointer, and flag words and bytes.
        Specifications of various useful BLWP and BL routines and
        associated data/flag items follow.  Some others, mostly data and
        flags, are specified in FWDOC/REPT.   The XOP instruction is
        poorly supported on the 99/4a, and is left for application
        programs to use.


        (A)  BLWP UTILITY ROUTINE VECTORS
        ~~~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~


         (1)  DSRLNK EQU  >FFD4
         ---  -----------------

             This provides a bare-bones DSRLNK function equivalent to
        that in the TI-Writer Editor but corrected to be compatible with
        multiple RS232 cards.  It is for file access only and does NOT
        take a following DATA 8 or DATA >A instruction.  This seemed
        like a good idea in pre-historic times when FUNNELWEB was only a
        TI-Writer interface and has stuck for reasons of consistency
        ever since.  Never mind, this sort of thing happens all the time
        - MS-DOS still smells like CP/M and Intel's i486 microprocessor
        still suffers gigantic hangovers fron the 8080.

             After the usual setup of a PAB in VDP and PAB pointer in
        PAD, call the DSRLNK as

                   BLWP @DSRLNK
                   JEQ  error handler
                   ..

             Further error trapping from the PAB error bits and GPL
        status is up to the programmer.  FUNNELWEB utilities regularly
        use this DSRLNK for subprogram access by the code sequence

            DSRTYP EQU  >7A

                   MOV  @DSRLNK+2,R11
                   INCT @DSRTYP(R11)
                   BLWP @DSRLNK
                   JEQ  DSERR

                   DECT @DSRTYP(R11)
                   success exit

            DSERR  DECT @DSRTYP(R11)
                   failure exit

             The offset value DSRTYP will be maintained at this value.
        All exits must restore the offset value correctly.


         (2)  KSCANA EQU  >FFD0
         ---  -----------------

             This is an enhanced KSCAN routine which may be used in
        place of the normal E/A utility.  It provides some extra
        functions transparently by setting processor status bits, which
        may then be tested by various conditional Jump instructions as
        required.  There are 6 condition bits available, and the tests
        check these separately.

                   BLWP @KSCANA
                   JNC -->> <escape> --> Jump
                   JOP -->> <No Key> --> Jump
                   JNO -->> <Proc'd> --> Jump
                   JEQ -->> <OldKey> --> Jump
                   JGT -->> <Enter>  --> Jump
                   JH  -->> <Redo>   --> Jump (New key only)

             <Escape> senses both <fctn-9> and <ctrl-C>, and <proceed>
        checks both <fctn-6> and <ctrl-A>.   Finally an unconditional
        JMP may be used to loop on the keyscan after one or more other
        tests.


         (3)  FILENT EQU  >FFCC
         ---  -----------------

             This provides a single line Editor typically used for entry
        of file and device names, and may be used in text mode as well
        from Vn 4.40 onwards.  The flashing cursor has auto-repeat with
        acceleration, and the timing parameters are set on entry to
        FUNNELWEB.  Editing keys are as described for filename entry.
        FILENT waits on entry until the previous key is released.
        Typical calling sequence is

                   BLWP @FILENT
                   DATA <scrpos>
                   BYTE <init offset>
                   BYTE <length>

             The initial offset gives the initial position of the cursor
        in the entry window, with null being the first position.  The
        CPU buffer is assigned after entry to the routine, immediately
        following the workspace.  The workspace is at >8302 in the PAD
        area, so the maximum buffer length can extend at most to the end
        of the DSR transient area.  A calling sequence that allows
        another workspace/buffer area to be assigned is

                BLWP @FWFILN
                DATA <scrpos>
                DATA <ofs,len>
                ..

         FILNT  EQU  $
                MOV  @FILENT+2,R11  FILENT code pointer in R11
                RT                  Return via FILENT RTWP

         FWFILN DATA FEWSP,FILNT     User "FILENT" BLWP vector
         FEWSP  BSS  >20             New workspace
         FILBFR BSS  <as needed>     Follows new workspace

             This is a lot simpler than writing your own routine, and
        may be necessary if you are already using the PAD area.  Several
        auxiliary flag locations are associated with use of FILENT.

             LOWCAS EQU >FF22    Lower case allowed
             HEXDIG EQU >FF24    HEX digits only
             ESFLAG EQU >FF60    <escape> flag/pointer


             When LOWCAS is null, the normal condition, all entries are
        converted to upper case as in the Editor SF/LF.  FILENT always
        resets LOWCAS to null on exit.  SETO of LOWCAS before calling
        FILENT allows lower case alpha characters to slip through.  If
        HEXDIG is set before entry only valid hex digits can be entered
        and deletes produce "0" instead of blanks.  Write a valid hex
        entry on the screen first as this is not checked.

             If ESFLAG is null then the <escape> key is ignored
        internally and the key value passed out.  SETO of ESFLAG is
        reserved for internal purposes.  Any other value is treated as
        an <escape> address pointer.  First instruction in the <esc>
        routine should be a LWPI as the <esc> sensing occurs in the
        internal CURSOR (see later) routine and will exit with the
        FILENT registers set.


         (4)  DELSPR EQU  >FFC8
         ---  -----------------

             This one just writes byte >D0 to VDP memory at >300 to shut
        off the sprite list in Graphics mode I with normal E/A table
        positions.  It is useful in quick cleanups after switching back
        from Text mode.  Just call as is.


         (5)  VMBWD  EQU  >FFBA
         ---  -----------------

             VMBWD gives a VMBW function from in-line data, which saves
        program space when using fixed value data.  Null length is just
        ignored.  Call as

                BLWP @VMBWD
                DATA <scrpos>
                DATA <CPU data>
                DATA <length>

             The primary FUNNELWEB workspace is at >FF7C, and R9 of this
        workspace always points to VMBWD so that it may be called from
        this workspace as BLWP *R9 making a 4 word total call.


         (6)  VMBRD  EQU  >FFB6
         ---  -----------------

             This is the VDP read version and is essentially similar to
        VMBWD.


         (7)  VSBRD  EQU  >FFB2
         ---  -----------------

             The calling sequence for this is

                BLWP @VSBRD
                DATA <scrpos>

        and it returns the byte in VDP memory at <scrpos> to the MSB of
        R0 (not the usual R1 in E/A code).


         (8)  VFILL  EQU  >FFAE
         ---  -----------------

             This fills a block of VDP RAM with the byte value in the
        MSB of R0.  The FUNNELWEB main workspace FWREGS EQU >FF7C
        maintains R8 as a pointer to this so that it may be called as
        BLWP *R8 etc.  Standard calling sequence is

               LI   R0,<MSB value>
               BLWP @VFILL
               DATA <scrpos>
               DATA <length>


         (9)  VMBWR  EQU  >FED4
         (10) VMBRR  EQU  >FED0
         (11) VSBWR  EQU  >FECC
         (12) VSBRR  EQU  >FEC8
         ---- -----------------

             This bunch of VDP utilities is equivalent to the standard
        E/A utility set in usage.  The VM routines check for and ignore
        null length values in R2.


         (13) VSTRW  EQU  >FEC4
         ---- -----------------

             This writes the body of a string with leading length byte
        to VDP.  Call as

               LI   R0,<string ptr>
               BLWP @VSTRW
               DATA <scrpos>

             If the length byte of the string is null then the call is
        ignored.


         (14) CURSOR EQU  >FEC0
         ---- -----------------

             The CURSOR routine is called internally by FILENT, but may
        also be called externally.  The calling sequence is

               LI   R6,<scrpos>
               BLWP @CURSOR

             CURSOR flashes at the screen position specified in the
        calling R6, and returns the key-value in the MSB of the calling
        R2, and this is left in raw state at console KEYRT (>8375) .
        See FILENT for a discussion of <escape>.  Normally CURSOR
        provides the up-case function for FILENT, so the LOWCAS flag is
        effective here also.  It is not cleared however except by the
        <escape> path.  If you want to use CURSOR externally with hex
        digit validation, you will need to supply your own validation
        routine.  A table of hex digits "01..EF" is provided at

             HXTAB  EQU  >FEA4

             The cursor flash rate and auto-delays are slaved indirectly
        to the VDP vertical interrupt rate.  On entry to FUNNELWEB the
        number of console keyscans that occur in an interval of 14
        vertical interrupts is counted and stored at

             REPETS EQU  >FEE4

             This does not account for the difference between PAL and
        NTSC consoles, but this will be minor compared to possible
        Geneve to 99/4a difference.


         (14) DSRREN EQU  >FEBC
         ---- -----------------

              DSRREN is intended to give a direct DSR re-entry from
        saved values, as is done in the E/A object loader, or more
        comprehensively in LINEHUNTER.  It re-enters the last DSR ROM at
        the same entry point directly without having to search for it.
        All PAB information necessary after this DSR entry must be
        supplied as normal.  It is used in DiskReview (80-col) as the
        new speedup for Vn 4.40 of the Myart file viewer.  It is of
        course not necessary to set the DSRTYP again for sub-program
        (eg sector read) re-entry as this is only needed to find the
        entry point in the original search.

             The relevant DSR values are stored in a 4 word block
        starting at

             SAVENT EQU >FF46

        on every full DSRLNK call.


         (15) QDCODE EQU  >FEB8
         ---- -----------------

             This is mostly of use internally after the AID key has been
        detected in the path with SETO of ESFLAG (>FF60).  It checks the
        value at AIDFL (>FF3A) and if null returns directly, else it
        branches to the address pointed to by AIDFL.  Usually this is a
        QD test/load/branch routine.


         (16) SETGRD EQU  >FEB4
         ---- -----------------

             This sets the GROM address using the system GROM pointer in
        GPL R13, so that Module Library banking is supported.  Call as

              LI   R0,<grom address>
              BLWP @SETGRD


        (B)   INDIRECT BL ROUTINE POINTERS
        ~~~   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

             All of these routines are conveniently called by

              MOV  @BLPTR,R11
              BL   *R11

        together with whatever register and/or in-line data is
        appropriate for the particular BL call.


         (1)  CFILE# EQU  >FFA6        Uses R0,R1
         ---  -----------------

        This takes a trailing DATA item >0n00 where "n" is the number of
        file buffers to be set aside in VDP as would be done with CALL
        FILES(n) from BASIC.  The routine is compatible with V-9938
        based systems, and rewrites MAXMEM (>8370) to suit.  A new VDP
        header is written for TI/CorComp disk controllers and VDP
        cleared above that to the top of the disk DSR area.  No range
        checking is done on "n".


         (2)  KEY    EQU  >FFA4         Uses R2
         ---  -----------------

             This keyloop enables interrupts, follows the previous
        prescription for <escape> and ESFLAG (>FF60), and calls QDCODE
        if AID is pressed.  The key return is placed in the MSB of R2
        and left unchanged at KEYRT (>8375).


         (3)  RESTR  EQU  >FFA2        Uses  R0.R1,R15
         ---  -----------------

             This does various housekeeping tasks to set up the E/A
        Graphics I mode for the FUNNELWEB Central Menu screen.  It
        resets the VDP registers to E/A default, rewrites the color
        table, clears the screen, calls DELSPR, restores the CHR(>81)
        pattern to underline, and restores the key-unit to 5.


         (4)  RDDEV  EQU  >FFA0        Uses R0,R1,R2,R3
         ---  -----------------

             The RDDEV routine handles the details after screen entry
        of a file or device name, saving the device name to CPU RAM, and
        building a PAB in VDP for DSRLNK.  RDDEV is called externally as

               MOV  @RDDEV,R11       Get pointer
               BL   *R11             Go to routine
               DATA <screen ptr>     Entry pointer on screen
               DATA <cpu ram bfr>    CPU RAM buffer for name
               DATA <vdp PAB adr>    VDP address for PAB
               DATA <cpu PAB data>   PAB data storage address
               ..

             The first data item is the VDP pointer for the filename as
        entered on screen.  RDDEV parses this up to the first space and
        enters it with leading length byte at the CPU RAM buffer pointed
        to by the second data item.  It then builds a PAB in VDP at the
        address in the third data item, using PAB data in CPU RAM
        pointed to by the fourth data item.  The CPU RAM buffer may well
        be a continuation of the PAB data, but need not be.  While at it
        RDDEV clears the GPL status byte (>837C) and loads SCNAME
        (>8356) for DSRLNK.


         (5)  QDLOAD  EQU  >FF3C    Uses R0,R1,R2,R10,R12
         ---  ------------------

               System files with 2 character filenames in E/A program
        file format may be loaded without executing by QDLOAD.  A
        typical calling sequence is

               MOV   @QDLOAD,R11    Get pointer
               BL    *R11           Execute
               DATA  'UL'           2-char filename
               DATA  ULPOS          Load position in CPU
               DATA  ULLEN          Load length
               JMP   <error return>
               ..

             Successful loads step over the error branch.  The normal
        E/A header is ignored in favor of the load target position and
        length.  The maximum file length allowed is >1100 which is long
        enough for QD or QF.  The file is loaded from the FUNNELWEB boot
        path as for other system files.

         (4)  FILCLN  EQU  >FEDC    Uses R0,R1,R10,R14
         ---  ------------------

               This routine cleans up the mailbox (>A000 - >A050) area,
        supplying the Utility pathname if nothing starting like a valid
        filename is found.


        (C)  DATA POINTERS
        ~~~  ~~~~~~~~~~~~~

             Other BL routines, data, code fragments, and pointers are
        for internal system use and may be subject to change in function
        or auxiliary conditions.  Some not already mentioned which may
        be useful are

             NAMBUF EQU  >FF62

             The space from NAMBUF to FWREGS (>FF7C) is used a filename
        buffer by the various loaders.  It is long enough to accomodate
        length byte and 25 character name (DSK.volname.filename or
        whatever else fits).  Increase in this was the one change that
        would have forced major incompatibilities with previous
        versions, and so it has been left as is for better or for worse.

             BTLN   EQU  >FF58

             This points to the length byte of the boot pathname and all
        references to system filenames are by offsets from this value.
        The Editor printer device name, as a survival from much earlier
        versions, though part of this block has its own pointer at
        EDPRNT EQU >FF1E.  All these path/file and device names are
        stored with leading length byte, unlike the workfile name in the
        mailbox at >A000 which is stored without length byte as required
        by the Editor.

             INCOL  EQU  >FF26

             The word value here is an index, range 0-9, into the 10
        byte table of color bytes for use in VReg #7, and pointed to by
        COLRS EQU >FF1C.  Standard Funnelweb system practice is always
        to use this table as the source of color combinations, and to
        use INCOL as index.  This helps avoid unexpected and jarring
        color changes on return.

             CPUDEL EQU  >FEE2

             The value here estimates CPU speed as seen from normal
        expansion RAM by counting a loop against the VDP interrupt
        timer.  It is handy as a value for CPU delay timing of beeps and
        bloops.  Use REPETS (see earlier) for keyloop timings.



ÇÄÇ╬ïÉòƒ⌐│╜╟╒╒╒╒╒╒╒╒ÇôÇæÇ╦ïÉòƒ⌐│╜╟╒╒╒╒╒╒╒╒Çô