$if 0
    ķ                        PowerBASIC v3.20
 Ĵ          DASoft          ķ
   Ķ    Copyright 1995     DATE: 1995-10-01 ķ
    FILE NAME   X-TREE  .TXT           by            
                               Don Schullian, Jr.                      
   ͼ                                          
  A license is hereby granted to the holder to use this source code in   
  any program, commercial or otherwise,  without receiving the express   
  permission of the copyright holder and without paying any royalties,   
  as long as this code is not distributed in any compilable format.      
   IE: source code files, PowerBASIC Unit files, and printed listings    
 ͼ 
                   ....................................                   
   ͼ
$endif

DOS sends file and disk data back through a series of interrupts and in
a buffer called the DTA ( Data Transfer Area ). There are several low
level DOS calls in this library that are not completely documented here
due to their very low level nature. The services that they provide are,
however, all available to you through other, higher order functions and
routines. If you wish to experiment with them they are listed with brief
explanations as to their functions on the last page of this file.

ANATOMY OF A BYTE:   &b00100001
                        bit 0 value   1
                        bit 1 value   2
                        bit 2 value   4
                        bit 3 value   8
                        bit 4 value  16
                        bit 5 value  32
                        bit 6 value  64
                        bit 7 value 128

This is a good time to go into BITMAPs. As DOS uses them extensively you
need to have some idea of what is going on.  So, let's take a minute and
get you up to speed on BITs and BYTEs.

The easiest way to work with bit-maps is to use BINARY numbers.  And our
example ( above ) is displayed in this format.  Notice that the BYTE has
8 bits and each bit has a position number ( 7 -> 0 ) and a corresponding
decimal value. Bits 0 and 5 are "ON" so the decimal value of the byte is
33. Which can either be 1) the value 33
                        2) the character "!"
                        3) 2 yes and 6 no answers
                        4) 1 of 256 possible answers

Let's say I've got a list of 5 jobs. Any or all of them can be done and I
only need to know which, if any, you want done. To DIM a BYTE array
Jobs?( 0:4 ) would do the trick,  so would a string of five "Y"s and "N"s
but all this can be put into a single BYTE and still have room left over!

       EXAMPLE:   Jobs? = &b00010101
                  IF Jobs? AND &b00000001 THEN
                    ' bit 0 is "ON" in both numbers so we'll do this one
                  END IF
                  IF Jobs? AND &b00000010 THEN
                    ' bit 1 is "OFF" in Jobs? so this one is skipped
                  END IF

When working with "AND", "OR", "XOR", etc. you need 2 bit-maps.  The one
on the right is the controller or MASK. It lets the program determine if
the task is to be done or not.   As you can see by the example above the
0th, 2nd, and 4th IFs will be processed and the rest will not. You could
also have asked: IF ( Jobs? AND &b00010001 ) THEN .... and it would have
been just as correct.

Of course, if you need more than 8 selections you can use WORDs that
have 16 bits or DWORDs that have 32 bits.  Think of the savings involved
if you had to store 32 answers to Y/N questions: you could store 32bytes
in an ARRAY or 4bytes in a BIT-MAP!

DOS, however, goes one step further in using available space.  They have
a habit of assigning a number of bits to hold a value then  "SHIFT" bits
and mask bits off ( XOR ) to get to the particular set of bits they want
the value for.
  EXAMPLE:  &b0000000000000000    FILE DATE
              ĴĴ DAY   bits 0 ->  4
                        MONTH bits 5 ->  8
                     YEAR  bits 9 -> 15

  EXAMPLE:  &b0000000000000000    FILE TIME
              ĴĴ SECONDS bits  0 ->  4 ( * 2 )
                        MINUTES bits  5 -> 10
                   HOURS   bits 11 -> 15

These may not be the smartest way to store  the data but in ASSEMBLY it
causes a lot less problem than it does in BASIC and that's the way things
are! End of lesson! I hope we have made things a little clearer for you.
You really don't need any of this when working with the routines in
DAS-2L2S.PBL as I have provided higher order functions that will return
numbers more "humanised" for you to use.  Bit mapping and masking is,
however, a very powerful tool to the programmer and you should take the
time to become familiar with it.

' 
'                                                        
' 

It is not, normally, my way to leave those who don't understand or know how
to use one of the routines in the dark but some of the low-level functions
that support of the higher-level functions are made available to those who
understand them. It is way beyond the capability of this library to teach
their use. I do not mean to discourage anyone but I'm afraid I have to leave
you to your own devices here:(

A word of caution: before attempting to use them learn where the reset button
                   is on your computer, you'll be needing it!

fDIRfirstFILE%  locate first file that matches Mask$
fDIRnextFILE%   locate next file in order
fDIRfile$       returns the file's name
fDIRattr?       returns the file's attribute value
fGetDTA$        read DTA into a string
 PutDTA         replace/overwrite DTA
fDTAPTR???      FARPOINTER to the DTA
fDIRtime??      a file's time in DOS style
fDIRdate??      a file's date in DOS style
fDIRsize&       a file's size in bytes
 DIRtime        a file's time in H,M,S
 DIRdate        a file's date in Y,M,D
fGetFirstDir%
fGetNextDir%
fSubDirName$

File Attributes:                    &b00111111    BIT-MAP
                  32 Archive File ٳ
                  16 Directory    ٳ
                   8 Volume Label ٳ
                   4 System File  ٳ
                   2 Hidden File  ٳ
                   1 Read Only    
