home *** CD-ROM | disk | FTP | other *** search
/ BBS 1 / BBS#1.iso / communic / x00150.ha / CHLLAPI.HA / CHLLAPI.DOC < prev    next >
Encoding:
Text File  |  1995-06-19  |  6.7 KB  |  165 lines
  1.  
  2.  
  3.  
  4.  
  5.             Why use the C 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.                 CHLLAPI
  64.  
  65.     I am not a C programmer, so please forgive any documentation
  66.     blunders and or systax errors in the example C code fragments.
  67.  
  68.     Now included in the X00 distribution are 5 object modules that allow
  69.     access to all X00 functions from Microsoft C.  A different object
  70.     file is included for each memory model.  Just is case you can not
  71.     figure it out:
  72.  
  73.         CSMALL.OBJ    is for small model programs
  74.         CMEDIUM.OBJ    is for medium model programs
  75.         CCOMPACT.OBJ    is for compact model programs
  76.         CLARGE.OBJ    is for large model programs and
  77.         CHUGH.OBJ    is for huge model programs
  78.  
  79.     Additionally, a file (X00.H) is included to provide the prototypes.
  80.     All of these files are in the archive CHLLPAI.ARC.  Some of the
  81.     object modules are identical.  I thought it best to include an
  82.     object module for each model to protect the innocent.  All of these
  83.     modules provide an identical (looking) interface to X00 for the
  84.     various memory models.
  85.  
  86.     Two routines are defined, they are X00 and X00X (defined with upper
  87.     case).  These routines are intended to be near direct replacement
  88.     routines for the C library functions int86 and int86x respectively.
  89.     The only difference in the calling sequence(s) is that the interrupt
  90.     number is not passed as a parameter.
  91.  
  92.     To use these interfacing routines, the programmer basically sets
  93.     variables is a structure that corresponds to the processor's
  94.     registers and passes the structure address(s) to X00 or X00X.  When
  95.     X00 or X00X is invoked, it copies the variables in the structure
  96.     to the processor's registers and then calls X00. Upon return from
  97.     X00, all of the processor's registers are copied into the output
  98.     structure.  The input structure and output structure may be the same.
  99.     In the case of X00X, a third structure address is passed.  This
  100.     structure is used as both input and output for segment registers
  101.     values.
  102.  
  103.     For a more complete description of the C structures and their uses,
  104.     read the documentation about the library functions int86 and int86x
  105.     in the appropriate Microsoft C reference manual.  These routines
  106.     may work with other C compilers, but have only been tested with
  107.     Microsoft's C.  I am told that Turbo C is identical.  X00 and X00X
  108.     do not use the data segment so the small model should also work
  109.     for Turbo C's Tiny model.
  110.  
  111.     The code fragments below (written by a C programmer) are intended
  112.     to provide examples of replacing int86 and int86x calls with X00
  113.     and X00X calls.
  114.  
  115.     My thanks to Doug Boone for helping with documentation and testing
  116.     the C HLLAPI.
  117.  
  118.     #include <dos.h>
  119.     #include "X00.h"
  120.  
  121.     union    REGS     regs;
  122.     struct    SREGS    sregs;
  123.  
  124.     char    input_bufr[1024];
  125.     char    far *input_ptr;
  126.  
  127.     /*
  128.     ==============================================================*/
  129.  
  130.     /* If you are using int86 calls then substitute: */
  131.          int86(0x14, ®s, ®s);
  132.     /* with */
  133.          X00(®s, ®s);
  134.  
  135.     /* If you are using int86x calls then substitute: */
  136.          int86x(0x14, ®s, ®s, &sregs);
  137.     /* with */
  138.          X00X(®s, ®s, &sregs);
  139.  
  140.     /*
  141.     ==============================================================
  142.     First, A call to X00X (this loads segment registers)          
  143.     ============================================================== */
  144.         input_ptr = (far *) input_bufr;
  145.         regs.h.ah = 0x18;        /* Block Read func code */
  146.         regs.x.di = FP_OFF(input_ptr);    /* Buffer offset to DI */
  147.         sregs.es = FP_SEG(input_ptr);    /* Buffer Segment to ES */
  148.         regs.x.cx = 1024;        /* Max bytes to xfer to CX */
  149.         regs.x.dx = 0;            /* Using COM1 (Port 0) */
  150.         X00X(®s, ®s, &sregs);
  151.  
  152.     /* Upon return, regs.x.ax contains the actual number of characters
  153.        put into input_bufr */
  154.  
  155.     /*
  156.     ==============================================================
  157.     This is a call to X00
  158.     ==============================================================*/
  159.         regs.h.ah = 0x03;        /* Stat Request func code */
  160.         regs.x.dx = 0;            /* Using COM1 (Port 0) */
  161.         X00(®s, ®s);
  162.     
  163.     /* Upon return, regs.x.ax contains the returned status for COM1 */
  164.  
  165.