home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / BBS / X00V124.ZIP / QBHLLAPI.ZIP / QBHLLAPI.DOC next >
Text File  |  1990-07-14  |  7KB  |  160 lines
  1.  
  2.  
  3.  
  4.  
  5.             Why use the Quick Basic 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 avoided.  Thus, the multitasker has no
  51.     opportunity to change the registers and all X00 functions should
  52.     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.  
  64.  
  65.  
  66.  
  67.  
  68.                 QBHLLAPI
  69.  
  70.     I am not a Basic programmer, so please forgive any documentation
  71.     blunders and/or syntax errors in the example Basic code fragments.
  72.  
  73.     Now included in the X00 distribution is an object module that allows
  74.     access to all X00 functions from Quick Basic.  That module is:
  75.  
  76.         QBX00.OBJ
  77.  
  78.     Two routines are defined in this module, QBX00 and QBX00X.
  79.     These routines are intended to be direct replacements for X00
  80.     calls when using the Quick Basic statements CALL INTERRUPT,
  81.     CALL INTERRUPTX, CALL INT86OLD and CALL INT86XOLD.  The only
  82.     difference in the calling sequence(s) is that the interrupt number
  83.     is not passed as a parameter.
  84.  
  85.     To use these interfacing routines, the programmer basically sets
  86.     variables is a structure that corresponds to the processor's
  87.     registers and passes the structure's address to QBX00 or QBX00X.
  88.     When QBX00 or QBX00X is invoked, it copies the variables in the
  89.     structure to the processor's registers and then calls X00.  Upon
  90.     return from X00, all of the processor's registers are copied into
  91.     the output structure.  The input structure and output structure
  92.     may be the same.
  93.  
  94.     In order to provide convenient access to the QBX00 routines from
  95.     the Quick Basic 4 environment, QBX00.OBJ should be converted
  96.     into regular library (.LIB) and Quick Library (.QLB) formats.
  97.     This can be accomplished by issuing the following DOS commands:
  98.  
  99.                LIB QBX00 +QBX00;
  100.                LINK /Q QBX00,,,BQLB45
  101.  
  102.     For a more complete description of the structures and their uses,
  103.     read the documentation about the library functions INTERRUPT,
  104.     INTERRUPTX, INT86OLD and INT86XOLD in the appropriate Microsoft
  105.     Quick Basic reference manual.  Also see the include file QB.BI
  106.     which comes on your Quick Basic disks.
  107.  
  108.     The code fragments below are intended to provide examples of
  109.     replacing INTERRUPT, INTERRUPTX, INT86OLD and INT86XOLD calls with
  110.     QBX00 and QBX00X calls.
  111.  
  112.     My thanks to Scott Barnes for helping with documentation and testing
  113.     the Quick Basic HLLAPI.
  114.  
  115. '** Sample QuickBasic 4.xx calls to X00.
  116.  
  117. '$INCLUDE: 'QB.BI'
  118.  
  119. DECLARE SUB QBX00 (inreg AS RegType,outreg AS RegType)
  120. DECLARE SUB QBX00X (inreg AS RegTypeX, outreg AS RegTypeX)
  121.  
  122. COMMON SHARED INREG AS REGTYPE, OUTREG AS REGTYPE
  123. COMMON SHARED INREGX AS REGTYPEX, OUTREGX AS REGTYPEX
  124.  
  125.     PORTNUM = 0                     'For COM1: operations
  126.  
  127. '** EXAMPLE 1: Initialize X00 driver and check initialization
  128.     INREG.AX = &H400                        'FOSSIL function 04h
  129.     INREG.DX = PORTNUM                      'Port number (0=COM1)
  130.     INREG.FLAGS = 512                       'Keeps interrupts enabled
  131.     CALL QBX00(INREG, OUTREG)               'Call X00
  132.     IF OUTREG.AX <> &H1954 THEN             'If installed X00 returns &H1954
  133.         PRINT "FOSSIL driver not found!"
  134.         STOP
  135.     ELSEIF (OUTREG.BX \ 256) < 5 THEN       'Is FOSSIL level 5 supported
  136.         PRINT "FOSSIL driver does not support Level 5 commands."
  137.         GOTO SHUTDOWN
  138.     END IF
  139.  
  140. '** EXAMPLE 2: Transmit a string TXIT$ using FOSSIL's write block function
  141. '** Note: The INREGX/OUTREGX structures and CALL INTERRUPTX statement must be
  142. '         used since FOSSIL requires the ES register to be passed in the call.
  143.  
  144.     TXIT$ = "Sample data to be transmitted"
  145.     TXSTART = 1                              'Try to xmit entire string
  146.     MAXTX = LEN(TXIT$)                       'Total # of characters to xmit
  147.     INREGX.AX = &H1900                       'Write block function code
  148.     INREGX.DX = PORTNUM                      'Port number (0=COM1)
  149.     INREGX.FLAGS = 512                       'Keeps interrupts enabled
  150.     DO UNTIL TXSTART > MAXTX                 'Loop until entire string is sent
  151.          TXNOW$ = MID$(TXIT$, TXSTART)       '
  152.          INREGX.CX = LEN(TXNOW$)             'Length of to xmit
  153.          INREGX.ES = VARSEG(TXNOW$)          'Segment of string
  154.          INREGX.DI = SADD(TXNOW$)            'Offset of string
  155.          CALL QBX00X(INREGX, OUTREGX)        'Call X00
  156.          TXSTART = TXSTART + OUTREGX.AX      'Add chars actually sent
  157.     LOOP
  158.  
  159.  
  160.