home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / BBS / X00V124.ZIP / TPHLLAPI.ZIP / TPHLLAPI.DOC next >
Text File  |  1990-07-13  |  6KB  |  143 lines
  1.  
  2.  
  3.  
  4.  
  5.             Why use the Turbo Pascal HLLAPI
  6.  
  7.     Every multitasker that I have examined insists on managing INT
  8.     14h.  The FOSSIL specification is basically an extension of the
  9.     normal BIOS INT 14h functions.  However, in implementing a FOSSIL
  10.     with features that are not supported by BIOS's INT 14h, additional
  11.     registers were used to pass additional parameters.  Some
  12.     multitaskers will intercept the INT 14h calls and will alter
  13.     registers that are not normally used by BIOS.     Quarterdeck's tech
  14.     support confirmed to me that they may change the DS register when
  15.     DESQview intercepts an INT 14h  (when released, version 2.26  of
  16.     DESQview is supposed to correct this).  What this means is that
  17.     some FOSSIL functions will work correctly with a multitasker and
  18.     others will not.  Additionally, it means that if one application
  19.     program uses a FOSSIL function that another application does not
  20.     use, then one of the programs may work fine with a multitasker
  21.     and the other may not.
  22.  
  23.     My first task in solving problems with multitaskers was to
  24.     eliminate the need for X00 to be called using an INT 14h.  Starting
  25.     with version 1.20  of X00, I have included quick and dirty HLLAPI
  26.     routines for some high level languages.  More are yet to come.
  27.     Applications programmers should replace references to library
  28.     routines in their existing source with the replacement routine(s)
  29.     included in the X00 distribution file. Then include the appropriate
  30.     object module in the linking process.  At this writing, HLLAPIs are
  31.     included for:
  32.  
  33.        Microsoft C, all models
  34.        Borland's Turbo C
  35.        Borland's Turbo Pascal
  36.        Microsoft Quick Basic
  37.  
  38.         The first time the HLLAPI is called, it will determine if X00 is
  39.         the active FOSSIL.  If X00 is the active FOSSIL, then it will be
  40.         directly called instead of using INT 14h.  If X00 is not the
  41.         active FOSSIL, or if there is no FOSSIL, the HLLAPI will issue an
  42.         INT 14h.  After the first call to the HLLAPI, a maximum of only 4
  43.         assembly instructions are added to the execution thread no matter
  44.         what FOSSIL is installed.  The addition of 4 instructions to the
  45.         execution thread should have no effect on execution speed of the
  46.         application program.
  47.  
  48.     Using the HLLAPIs to access X00 with a multitasking system can
  49.     result in significantly faster execution because the multitasker's
  50.     management of INT 14h is not executed.  Additionally, the
  51.     multitasker has no opportunity to change the registers and all
  52.     FOSSIL functions should work correctly.
  53.  
  54.     Those using assembly language to access X00 should replace INT 14h
  55.     instructions with a CALL BYPASS and include BYPASS.OBJ in the linked
  56.     program.  BYPASS should be declared as a FAR external,
  57.     i.e.    EXTRN    BYPASS:FAR
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                 TPHLLAPI
  64.  
  65.         I am not a Pascal programmer, so please forgive any documentation
  66.         blunders and/or syntax errors in the Pascal code fragments.
  67.  
  68.         Now included in the X00 distribution is an object module that allows
  69.         access to all X00 functions from Turbo Pascal.  That module is:
  70.  
  71.                 TPX00.OBJ
  72.  
  73.         A single routine, TPX00, is defined, and is intended to be a direct
  74.         replacement for the Turbo Pascal INTR function when used with
  75.         interrupt 14h.  The only difference in the calling sequence is that
  76.         the interrupt number is not passed as a parameter.
  77.  
  78.         To use this interfacing routine, the programmer basically sets
  79.         variables in a structure that corresponds to the processor's
  80.         registers and passes the structure address to TPX00.  When TPX00
  81.         is invoked, it copies the variables in the structure to the
  82.         processor's registers and then calls the installed FOSSIL.  Upon
  83.         return from the FOSSIL, all of the processor's registers are
  84.         copied into the output structure.  The input structure and output
  85.         structure are the same.  That is, this structure is used as both
  86.         input and output for register values passed to and returned from
  87.         X00.
  88.  
  89.         For a more complete description of the Pascal structures and their
  90.         uses,  read the documentation about the function INTR in the
  91.         appropriate Turbo Pascal reference manual.  TPX00 may work with
  92.         other Pascal compilers, but has only been tested with Borland's
  93.         Turbo Pascal.
  94.  
  95.         The code fragments below are intended to provide examples of
  96.         replacing INTR calls with TPX00 calls.
  97.  
  98.         My thanks to Bob Klahn and Chris Irwin for helping with
  99.         documentation and testing the Turbo Pascal HLLAPI.
  100.  
  101.         CONST
  102.           Buffer_Size = 1024;
  103.  
  104.         VAR
  105.           Regs : REGISTERS;
  106.           Input_Buffer : ARRAY [1..Buffer_Size] OF BYTE;
  107.  
  108.         PROCEDURE Bypass; EXTERNAL;           {for inline code, yet to be doc'd}
  109.         PROCEDURE TPX00( VAR Regs : REGISTERS ); EXTERNAL;
  110.         {$L TPX00}
  111.  
  112.         PROCEDURE FOSSIL_Stuff;
  113.  
  114.         BEGIN
  115.           { Check for active FOSSIL }
  116.           Regs.AH := $04;  Regs.BX := 0;  Regs.DX := $00FF;
  117.           { INTR( $14, Regs ); is replaced with }
  118.           TPX00( Regs );
  119.           FOSSIL_Active := Regs.AX = $1954;
  120.  
  121.           IF FOSSIL_Active THEN
  122.             BEGIN
  123.               { Open FOSSIL port 0, COM1 }
  124.               Regs.AH := $04;  Regs.BX := 0;  Regs.DX := $0000;
  125.               { INTR( $14, Regs ); is replaced with }
  126.               TPX00( Regs );
  127.  
  128.               { Do a block read from the FOSSIL input buffer for COM1 }
  129.  
  130.               Regs.AH := $18;                  { Block read func code }
  131.               Regs.DI := OFS( Input_Buffer );  { Input buffer offset  to DI }
  132.               Regs.ES := SEG( Input_Buffer );  { Input buffer segment to ES }
  133.               Regs.CX := Buffer_Size;          { Max bytes to read to CX }
  134.               Regs.DX := 0;                    { Data from COM1 }
  135.               { INTR( $14, Regs ); is replaced with }
  136.               TPX00( Regs );
  137.  
  138.       { Upon return, Regs.AX will contain the number of bytes that X00 }
  139.       { placed into Input_Buffer. }
  140.  
  141.             END;
  142.  
  143.