   ________________________________________________________________________
   name: boostqb
   desc: speeds up:
         limul (LONG * INTEGER or LONG),
         lidiv (LONG \ INTEGER or LONG),
         limod (LONG MOD INTEGER or LONG),
         licmp (LONG <> < > = >= <= INTEGER or LONG) -> 32-bit proc

         fwait (used after floating-point calcs),
         SIN(SINGLE or DOUBLE),
         COS(SINGLE or DOUBLE),
         TAN(SINGLE or DOUBLE),
         ATN(SINGLE or DOUBLE) -> inline code

         DEF SEG -> inline code

         stack allocation -> local symbols cleared with stosd,
                             preserve all registers
  
   type: sub
   args: none
   retn: none
  
   decl: boostqb ()

   ex. : boostqb

   ________________________________________________________________________
   name: ProcPtr
   desc: gets a QB's 'SUB' or 'FUNCTION' address
  
   type: sub
   args: [out] ptr:long         | SUB's or FUNCTION's address
   retn: 'ptr' set
  
   decl: ProcPtr (ptr as long)

   ex. : dim myptr as long
         ProcPtr myptr                  '' myptr= address of MySub
         MySub 0, 0, 0                  '' this line will be skipped

         ...

         sub MySub (a%, b%, c%)
           ...
         end sub

   see : Procedure

   ________________________________________________________________________
   name: Procedure
   desc: calls a far pointer
  
   type: sub
   args: [in]  parameters...:any,
               ptr:long          | far pointer to call
   retn: none
  
   decl: Procedure (parameters... , ptr as long)

   obs.: don't explicitly declare this routine, use the CALL directive to
         invoke it.

   ex. : call Procedure(0, 0, 0, myptr)

   see : ProcPtr

   ________________________________________________________________________
   name: IntegerRet, LongRet and StringRet
   desc: returns an INTEGER, LONG integer or a string from QB's FUNCTIONs
         called using the 'Procedure' routine
  
   type: function
   args: none
   retn: integer, long, string  | function's result
  
   decl: IntegerRet% ()
         LongRet& ()
         StringRet$ ()

   obs.: must be used immediately after call the FUNCTION

   ex. : ProcPtr myptr                  '' myptr= address of MyFunc
         foo = MyFunc(0, 0, 0)          '' this line will be skipped

         call Procedure(0, 0, 0, myptr)
         result = IntegerRet

         function MyFunc% (a%, b%, c%)
           ...
         end function

   see : Procedure

   ________________________________________________________________________
   name: LabelPtr
   desc: gets a QB's 'LABEL' address
  
   type: sub
   args: [out] ptr:long         | LABEL's address
   retn: 'ptr' set
  
   decl: LabelPtr (ptr as long)

   ex. : dim myptr as long
         LabelPtr myptr                 '' myptr= address of MyLabel
         gosub MyLabel                  '' this line will be skipped

         ...
         end

         MyLabel:
         ...
         return

   see : MultiLabelPtr, GoLabel, JmpLabel

   ________________________________________________________________________
   name: MultiLabelPtr
   desc: gets multiple QB's 'LABELs' addresses
  
   type: sub
   args: [out] ptrArray:long    | array of pointers
         [in]  labels:integer   | number of addresses to get
   retn: 'ptrArray' filled
  
   decl: MultiLabelPtr (seg ptrArray as long, byval labels as integer)

   ex. : dim myptr(0 to 2) as long
         MultiLabelPtr myptr(0), 3      '' myptr()= address of MyLabel0,1,2
         gosub MyLabel0                 '' this line will be skipped
         gosub MyLabel1                 '' /
         gosub MyLabel2                 '' /

         ...
         end

         MyLabel0:
         ...
         return

         MyLabel1:
         ...
         return

         MyLabel2:
         ...
         return

   see : LabelPtr, GoLabel, JmpLabel

   ________________________________________________________________________
   name: GoLabel
   desc: calls a near pointer  (inline)
  
   type: sub
   args: [in]  ptr:long         | near pointer to call
   retn: none
  
   decl: GoLabel (byval ptr as long)

   ex. : GoLabel myptr

   see : LabelPtr, MultiLabelPtr, JmpLabel

   ________________________________________________________________________
   name: JmpLabel
   desc: jumps to a near pointer  (inline)
  
   type: sub
   args: [in]  ptr:long         | near pointer to call
   retn: none
  
   decl: JmpLabel (byval ptr as long)

   ex. : JmpLabel myptr

   see : LabelPtr, MultiLabelPtr, GoLabel

   ________________________________________________________________________
   name: SaveRegs
   desc: saves registers in REGS struct
  
   type: sub
   args: [out] rg:REGS          | struct to save the registers
   retn: 'rg' filled
  
   decl: SaveRegs (rg as REGS)

   ex. : dim myregs as REGS
         SaveRegs myregs

   see : RestoreRegs

   ________________________________________________________________________
   name: RestoreRegs
   desc: restores registers saved in REGS struct by SaveRegs routine
  
   type: sub
   args: [in]  rg:REGS          | struct w/ registers to restore
   retn: none
  
   decl: RestoreRegs (regs as REGS)

   ex. : RestoreRegs myregs

   see : SaveRegs
   
   ________________________________________________________________________
   name: PushAll
   desc: pushes all registers to stack
  
   type: sub
   args: none
   retn: none
  
   decl: PushAll ()

   ex. : PushAll

   see : PopAll, PushInt, PushLong

   ________________________________________________________________________
   name: PopAll
   desc: pops all registers from stack
  
   type: sub
   args: none
   retn: none
  
   decl: PopAll ()

   ex. : PopAll

   see : PushAll, PopInt, PopLong

   ________________________________________________________________________
   name: PushInt
   desc: pushes an INTEGER to stack  (inline)
  
   type: sub
   args: [in]  num:integer      | integer to push
   retn: none
  
   decl: PushInt (byval num as integer)

   ex. : PushInt num%

   see : PopInt, PushAll, PushLong

   ________________________________________________________________________
   name: PushLong
   desc: pushes a LONG integer to stack  (inline)
  
   type: sub
   args: [in]  lng:long         | long integer to push
   retn: none
  
   decl: PushLong (byval lng as long)

   ex. : PushLong lng&

   see : PopLong, PushAll, PushInt

   ________________________________________________________________________
   name: PopInt
   desc: pops an INTEGER from stack  (inline)
  
   type: sub
   args: [out] num:integer      | integer where to pop
   retn: 'num' set
  
   decl: PopInt (num as integer)

   ex. : PopInt num%

   see : PushInt, PushFlags, PopAll, PopLong

   ________________________________________________________________________
   name: PopLong
   desc: pops a LONG integer from stack  (inline)
  
   type: sub
   args: [out] lng:long         | long integer where to pop
   retn: 'lng' set
  
   decl: PopLong (lng as long)

   ex. : PopLong lng&

   see : PushLong, PopAll, PopInt

   ________________________________________________________________________
   name: PushFlags
   desc: generates a PUSHF (push flags) instruction  (inline)
  
   type: sub
   args: none
   retn: none
  
   decl: PushFlags ()

   ex. : PushFlags

   see : PopInt

   ________________________________________________________________________
   name: IntrReturn
   desc: generates an IRET (return from interrupt) instruction  (inline)
  
   type: sub
   args: none
   retn: none
  
   decl: IntrReturn ()

   ex. : IntrReturn

   see : FarReturn

   ________________________________________________________________________
   name: FarReturn
   desc: generates a RETF (far return) instruction  (inline)
  
   type: sub
   args: none
   retn: none
  
   decl: FarReturn ()

   ex. : FarReturn

   see : IntrReturn

   ________________________________________________________________________
   name: EnableIntr
   desc: generates a STI (set interrupt flag) instruction  (inline)
  
   type: sub
   args: none
   retn: none
  
   decl: EnableIntr ()

   ex. : EnableIntr

   see : DisableIntr
   
   ________________________________________________________________________
   name: DisableIntr
   desc: generates a CLI (clear interrupt flag) instruction  (inline)
  
   type: sub
   args: none
   retn: none
  
   decl: DisableIntr ()

   ex. : DisableIntr

   see : EnableIntr

   ________________________________________________________________________
   name: SetDGroup
   desc: sets DS segment register to DGROUP  (inline)
  
   type: sub
   args: none
   retn: none
  
   decl: SetDGroup ()

   ex. : SetDGroup

   ________________________________________________________________________
   name: MakeLong
   desc: joins two INTEGERs, msw (most significant word) and
         lsw (less significant word), returning a LONG integer
  
   type: function
   args: [in]  msw,lsw:integer  | integers to join
   retn: long                   | integers joined
  
   decl: MakeLong& (byval msw as integer, _
                    byval lsw as integer)

   ex. : lng& = MakeLong(msw%, lsw%)

   see : BreakLong

   ________________________________________________________________________
   name: BreakLong
   desc: breaks a LONG integer in msw (most significant word) and
         lsw (less significant word)
  
   type: sub
   args: [in]  lng:long         | long integer to break
         [out] msw,lsw:integer  | result
   retn: 'msw' and 'lsw' set
  
   decl: BreakLong (byval lng as long, _
                    msw as integer, _
                    lsw as integer)

   ex. : BreakLong lng&, msw%, lsw%

   see : MakeLong

   ________________________________________________________________________
   name: peekb, peeki, peekl
   desc: gets a byte, integer or long integer from memory  (inline)
  
   type: function
   args: [in]  src:long         | memory address to get from
   retn: byte, integer, long    | byte, integer or long read
  
   decl: peekb%  cdecl (byval src as long)
         peekb2% cdecl alias "_peekb" (byval ofs as integer, _
                  byval segm as integer)
         peeki%  cdecl (byval src as long)
         peeki2% cdecl alias "_peeki" (byval ofs as integer, _
                  byval segm as integer)
         peekl&  cdecl (byval src as long)
         peekl2& cdecl alias "_peekl" (byval ofs as integer, _
                  byval segm as integer)

   ex. : i% = peekb (&hA0000000)
         i% = peekb2(&h0000, &hA000)
         i% = peeki (&hA0000000)
         i% = peeki2(&h0000, &hA000)
         l& = peekl (&hA0000000)
         l& = peekl2(&h0000, &hA000)

   see : pokeb, pokei, pokel

   ________________________________________________________________________
   name: pokeb, pokei, pokel
   desc: writes a byte, integer or long integer to memory  (inline)
  
   type: sub
   args: [in]  dst:long,        | memory address to write to
               value:integer,\
                     long       | byte, integer or long to write
   retn: none
  
   decl: pokeb  cdecl (byval dst as long, _
                 byval value as integer)
         pokeb2 cdecl alias "_pokeb" (byval ofs as integer, _
                 byval segm as integer, _
                 byval value as integer)
         pokei  cdecl (byval dst as long, _
                 byval value as integer)
         pokei2 cdecl alias "_pokei" (byval ofs as integer, _
                 byval segm as integer, _
                 byval value as integer)
         pokel  cdecl (byval dst as long, _
                 byval value as long)
         pokel2 cdecl alias "_pokel" (byval ofs as integer, _
                 byval segm as integer, _
                 byval value as long)

   ex. : pokeb  &hA0000000, &hFF
         pokeb2 &h0000, &hA000, &hFF
         pokei  &hA0000000, &hFFFF
         pokei2 &h0000, &hA000, &hFFFF
         pokel  &hA0000000, &hFFFFFFFF
         pokel2 &h0000, &hA000, &hFFFFFFFF

   see : peekb, peeki, peekl

   ________________________________________________________________________
   name: pointer
   desc: converts an address to far pointer
  
   type: function
   args: [in]  array:any        | address of array to convert
   retn: long                   | the far pointer
  
   decl: pointer& (seg array as any)

   ex. : ptr& = pointer(myarray(0))

   see : peek#, poke#

   ________________________________________________________________________
   name: redimabs
   desc: points an array to absolute memory location and defines its new
         subscripts
  
   type: sub
   args: [in]  subscripts...:integer,
               farptr:long,           | far pointer to absolute mem location
               array():any            | array descriptor to change
   retn: none
  
   decl: redimabs (subscripts ..., farptr, array())

   obs.: don't explicitly declare this routine, use the CALL directive to
         invoke it.
         array must be first declared using REDIM with subscripts of 0.

   ex. : redim myArray(0, 0) as integer
         call redimabs(320\2, 200, &hA0000000, myArray())
         myArray(319\2, 199) = &h0F0F

   ________________________________________________________________________
   name: shl, lshl, sal, lsal
   desc: shifts to left an integer or long integer  (inline)
  
   type: function
   args: [in]  times:integer,   | number of bits to shift
               number:integer or\
                      long      | number to shift
   retn: integer, long          | integer or long shifted
  
   decl: SHL%  cdecl (byval times as integer, _
                byval number as integer)
         LSHL& cdecl (byval times as integer, _
                byval number as long)
         SAL%  cdecl alias "_SHL" (byval times as integer, _
                byval number as integer)
         LSAL& cdecl alias "_LSHL" (byval times as integer, _
                byval number as long)

   obs.: shl and sal are synonym

   ex. : i% = SHL (0 .. 15, i%)
         i% = SAL (0 .. 15, i%)
         l& = LSHL(0 .. 31, l&)
         l& = LSAL(0 .. 31, l&)

   see : shr, lshr, sar, lsar

   ________________________________________________________________________
   name: shr, lshr, sar, lsar
   desc: shifts to right an integer or long integer  (inline)
  
   type: function
   args: [in]  times:integer,   | number of bits to shift
               number:integer or\
                      long      | number to shift
   retn: integer, long          | integer or long shifted
  
   decl: SHR%  cdecl (byval times as integer, _
                byval number as integer)
         LSHR& cdecl (byval times as integer, _
                byval number as long)
         SAR%  cdecl (byval times as integer, _
                byval number as integer)
         LSAR& cdecl (byval times as integer, _
                byval number as long)

   obs.: the SAR and LSAR functions are for signed INTEGERs or LONGs

   ex. : i% = SHR (0 .. 15, i%)
         i% = SAR (0 .. 15, i%)
         l& = LSHR(0 .. 31, l&)
         l& = LSAR(0 .. 31, l&)

   see : shl, lshl, sal, lsal

   ________________________________________________________________________
   name: rol, lrol
   desc: rotates to left an integer or long integer  (inline)
  
   type: function
   args: [in]  times:integer,   | number of bits to rotate
               number:integer or\
                      long      | number to rotate
   retn: integer, long          | integer or long rotated
  
   decl: ROL%  cdecl (byval times as integer, _
                byval number as integer)
         LROL& cdecl (byval times as integer, _
                byval number as long)

   ex. : i% = ROL (0 .. 15, i%)
         l& = LROL(0 .. 31, l&)

   see : ror, lror

   ________________________________________________________________________
   name: ror, lror
   desc: rotates to right an integer or long integer  (inline)
  
   type: function
   args: [in]  times:integer,   | number of bits to rotate
               number:integer or\
                      long      | number to rotate
   retn: integer, long          | integer or long rotated
  
   decl: ROR%  cdecl (byval times as integer, _
                byval number as integer)
         LROR& cdecl (byval times as integer, _
                byval number as long)

   ex. : i% = ROR (0 .. 15, i%)
         l& = LROR(0 .. 31, l&)

   see : rol, lrol
