





                               LOGICALS

                           -- THE MANUAL --

                               05/14/90
Logicals -- The Manual --                                             Page:   2
Tuesday  May 15, 1990   10:55:37 am



The functions here were written to add some of the bitwise functionality found
in Quicksilver to Clipper.  They are just a few simple functions to identify
and set integer bit masks, as well as to combine masks logically with AND, OR
and XOR functions.  They can be quite useful when doing BIOS/DOS calls, and
using a preprocessor to name various bit masks.

Logical Functions Included in LOGICALS.LIB:

bitwand() - Bitwise AND of two integers.
bitwor() - Bitwise OR of two integers.
bitwxor() - Bitwise XOR of two integers.

bitset() - Test whether specified bit is SET (1).
bitclear() - Test whether specified bit is CLEAR (0).

setbit() - Set specified bit to 1.
clearbit() - Clear specified bit to 0.

bitmap() - Fills first 16 positions of an array with True/False indications
            of whether corresponding bit is set.

     Bitset() and setbit(), as well as bitclear() and clearbit(), are easy to
keep straight in your mind if you look closely at the names.  The testing
functions bitset() and bitclear() begin with a noun (existence), the setting
functions setbit() and clearbit(), begin with verbs (action).

Sample linking batch files are also included - clipem.bat for Microsoft Link,
and cliplink.bat for Sage's PLink86 Plus.  To install, just copy LOGICALS.LIB
into the same directory as CLIPPER.LIB and EXTEND.LIB.

Logicals -- The Manual -- Registration                                Page:   3
Tuesday  May 15, 1990   10:55:37 am

Registration:

The functions in this mini-library are free for your use.  However,
they are also still under my copyright, and their source shall not
appear in any shareware version.  

I am also putting the finishing touches on more complete libraries
for Clipper, providing LaserJet control and mouse functions.  To
register, and receive information on these other products, please
send a copy of the form below.  Registration with source (if you
really need it) is sent for a donation of $7.50 and includes 25% off
the registration with source for the previously mentioned products.

REGISTRATION (Logicals)
-----------------------

Name:    __________________________________________     Date: __/__/__
       
Address: __________________________________________

Address: __________________________________________

City:    _______________________________,  State: _______  Zip: ________

Phone Number: (_____)  _____ - ________

Computer Type: ______________________________   DOS Version: ___________

Optional:

Company:  __________________________________________

Position: __________________________________________

Work Phone: (_____)  _____ - ________


_____ No donation.  Registration Only

_____ $7.50+ donation.  Please send me the source.

Send to: R. L. Korbeck,  17233 Hemmingway St.  Van Nuys, CA  91406

Logicals -- The Manual -- BitWAnd()                                   Page:   4
Tuesday  May 15, 1990   10:55:37 am

Function Name: BitWAnd()

Function Type: Numeric (Integer)

Syntax:        BitWAnd(Parameter 1, Parameter 2)

                 Parameter 1 - Numeric (Integer) - Number Input
                 Parameter 2 - Numeric (Integer) - Bit Mask

Object File:   logical1.obj

Description:   BitWAnd() takes two integers as parameters, returning
                 an integer which is the result of a bitwise AND of the
                 input integers.  If fewer than two parameters are input,
                 BitWAnd() returns 0.

Examples:      ? "BitWAnd(255, 15) = "
               ?? trim(str(bitwand(255, 15)))
               ? "BitWAnd(255) = "
               ?? trim(str(bitwand(255)))
               ? "BitWAnd(65, 33) = "
               ?? trim(str(bitwand(65, 33)))

               results in:

               BitWAnd(255, 15) = 15
               BitWAnd(255) = 0
               BitWAnd(65, 33) = 1


Logicals -- The Manual -- BitWOr()                                    Page:   5
Tuesday  May 15, 1990   10:55:37 am

Function Name: BitWOr()

Function Type: Numeric (Integer)

Syntax:        BitWOr(Parameter 1, Parameter 2)

                 Parameter 1 - Numeric (Integer) - Number Input 
                 Parameter 2 - Numeric (Integer) - Bit Mask

Object File:   logical2.obj

Description:   BitWOr() takes two integers as parameters, returning
                 an integer which is the result of a bitwise OR of the
                 input integers.  If fewer than two parameters are input,
                 BitWOr() returns 0.

Examples:      ? "BitWOr(255, 15) = "
               ?? trim(str(bitwor(255, 15)))
               ? "BitWOr(255) = "
               ?? trim(str(bitwor(255)))
               ? "BitWOr(65, 33) = "
               ?? trim(str(bitwor(65, 33)))

               results in:

               BitWOr(255, 15) = 15
               BitWOr(255) = 0
               BitWOr(65, 33) = 97


Logicals -- The Manual -- BitWXOr()                                   Page:   6
Tuesday  May 15, 1990   10:55:37 am

Function Name: BitWXOr()

Function Type: Numeric (Integer)

Syntax:        BitWXOr(Parameter 1, Parameter 2)

                 Parameter 1 - Numeric (Integer) - Number Input
                 Parameter 2 - Numeric (Integer) - Bit Mask

Object File:   logical3.obj

Description:   BitWXOr() takes two integers as parameters, returning
                 an integer which is the result of a bitwise XOR of the
                 input integers.  If fewer than two parameters are input,
                 BitWXOr() returns 0.

Examples:      ? "BitWXOr(255, 15) = "
               ?? trim(str(bitwxor(255, 15)))
               ? "BitWXOr(255) = "
               ?? trim(str(bitwxor(255)))
               ? "BitWXOr(65, 33) = "
               ?? trim(str(bitwxor(65, 33)))

               results in:

               BitWXOr(255, 15) = 240
               BitWXOr(255) = 0
               BitWXOr(65, 33) = 96


Logicals -- The Manual -- BitSet()                                    Page:   7
Tuesday  May 15, 1990   10:55:37 am

Function Name: BitSet()

Function Type: Logical

Syntax:        BitSet(Parameter 1, Parameter 2)

                 Parameter 1 - Numeric (Integer) - Number Input
                 Parameter 2 - Numeric (Integer) - Bit to Check

Object File:   logical4.obj

Description:   BitSet() takes two integers as parameters.  The first
                 is an integer value, the second the number of the bit
                 to be checked.  The bit to be checked must be in the
                 range 0 - 15.  If the corresponding bit is set, then
                 BitSet() returns True.  If the bit is not set, or if 
                 the requested bit number is not in the 0 - 15 range,
                 or if fewer than two parameters are input, then BitSet()
                 returns False.

Examples:      ? "BitSet(255, 15) = "
               ?? bitset(255, 15)
               ? "BitSet(255, 1) = "
               ?? bitset(255, 1)
               ? "BitSet(65, 33) = "
               ?? bitset(65, 33)
               ? "BitSet(65) = "
               ?? bitset(65)

               results in:

               BitSet(255, 15) = .F.
               BitSet(255, 0) = .T.
               BitSet(65, 33) = .F.
               BitSet(65) = .F.


Logicals -- The Manual -- BitClear()                                  Page:   8
Tuesday  May 15, 1990   10:55:37 am

Function Name: BitClear()

Function Type: Logical

Syntax:        BitClear(Parameter 1, Parameter 2)

                 Parameter 1 - Numeric (Integer) - Number Input
                 Parameter 2 - Numeric (Integer) - Bit to Check

Object File:   logical5.obj

Description:   BitClear() takes two integers as parameters.  The first
                 is an integer value, the second the number of the bit
                 to be checked.  The bit to be checked must be in the
                 range 0 - 15.  If the corresponding bit is clear, then
                 BitClear() returns True.  If the bit is set, or if 
                 the requested bit number is not in the 0 - 15 range,
                 or if fewer than two parameters are input, then
                 BitClear() returns False.

Examples:      ? "BitClear(255, 15) = "
               ?? bitclear(255, 15)
               ? "BitClear(255, 1) = "
               ?? bitclear(255, 1)
               ? "BitClear(65, 33) = "
               ?? bitclear(65, 33)
               ? "BitClear(65) = "
               ?? bitclear(65)

               results in:

               BitClear(255, 15) = .T.
               BitClear(255, 0) = .F.
               BitClear(65, 33) = .F.
               BitClear(65) = .F.


Logicals -- The Manual -- SetBit()                                    Page:   9
Tuesday  May 15, 1990   10:55:37 am

Function Name: SetBit()

Function Type: Numeric (Integer)

Syntax:        SetBit(Parameter 1, Parameter 2)

                 Parameter 1 - Numeric (Integer) - Number Input
                 Parameter 2 - Numeric (Integer) - Bit to be Set

Object File:   logical6.obj

Description:   SetBit() takes two integers as parameters, returning
                 an integer which is the number input as parameter 1
                 with the bit specified by parameter 2 being set.  The
                 number input as Parameter 2 must be in the range 0 - 15.
                 If the bit was already set, the result is the same as
                 parameter 1.  If it was not previously set, the result
                 is the same as (Param1 + 2^^Param2).  If fewer than two
                 parameters are input, or if Parameter 2 is not in the
                 range 0 - 15, then SetBit() returns 0.

Examples:      ? "SetBit(255, 15) = "
               ?? trim(str(setbit(255, 15)))
               ? "SetBit(255) = "
               ?? trim(str(setbit(255)))
               ? "SetBit(255, 1) = "
               ?? trim(str(setbit(255)))
               ? "SetBit(255, 9) = "
               ?? trim(str(setbit(255)))
               ? "SetBit(65, 33) = "
               ?? trim(str(setbit(65, 33)))

               results in:

               SetBit(255, 15) = 33023
               SetBit(255) = 0
               SetBit(255, 1) = 255
               SetBit(255, 9) = 767
               SetBit(65, 33) = 0


Logicals -- The Manual -- ClearBit()                                  Page:  10
Tuesday  May 15, 1990   10:55:37 am

Function Name: ClearBit()

Function Type: Numeric (Integer)

Syntax:        ClearBit(Parameter 1, Parameter 2)

                 Parameter 1 - Numeric (Integer) - Number Input
                 Parameter 2 - Numeric (Integer) - Bit to be Cleared

Object File:   logical7.obj

Description:   ClearBit() takes two integers as parameters, returning
                 an integer which is the number input as parameter 1
                 with the bit specified by parameter 2 being cleared.
                 The number input as Parameter 2 must be in the range
                 0 - 15.  If the bit was already clear, the result is
                 the same as parameter 1.  If it was not previously
                 cleared, the result is the same as (Param1 - 2^^Param2).
                 If fewer than two parameters are input, or if Parameter
                 2 is not in the range 0 - 15, then ClearBit() returns 0.

Examples:      ? "ClearBit(255, 15) = "
               ?? trim(str(clearbit(255, 15)))
               ? "ClearBit(255) = "
               ?? trim(str(clearbit(255)))
               ? "ClearBit(255, 1) = "
               ?? trim(str(clearbit(255)))
               ? "ClearBit(255, 9) = "
               ?? trim(str(clearbit(255)))
               ? "ClearBit(65, 33) = "
               ?? trim(str(clearbit(65, 33)))

               results in:

               ClearBit(255, 15) = 255
               ClearBit(255) = 0
               ClearBit(255, 1) = 254
               ClearBit(255, 9) = 255
               ClearBit(65, 33) = 0


Logicals -- The Manual -- BitMap()                                    Page:  11
Tuesday  May 15, 1990   10:55:37 am

Function Name: BitMap()

Function Type: Logical

Syntax:        BitMap(Parameter 1, Parameter 2)

                 Parameter 1 - Numeric (Integer) - Number Input
                 Parameter 2 - Array - Array to Store Values in.

Object File:   logical8.obj

Description:   BitMap() uses two parameters, the number for which the
                 map is being generated, and the array that holds the
                 map.  BitMap() returns a value of False if there are
                 less than two parameters passed, if the parameters are
                 not the correct types, or if the array is not large
                 enough to hold the sixteen values.  BitMap() doesn't
                 care if the array is larger than sixteen positions.
                 BitMap() will return a logical True value in all other
                 circumstances.

Examples:      declare Example[16]
               BitMap(255, Example)
               for n = 1 to 16
                 ShowString = "Bit[" + trim(int(n-1)) + "] = "
                 ? ShowString
                 ?? Example[n]
               next

               results in:

               Bit[0] = .T.
               Bit[1] = .T.
               Bit[2] = .T.
               Bit[3] = .T.
               Bit[4] = .T.
               Bit[5] = .T.
               Bit[6] = .T.
               Bit[7] = .T.
               Bit[8] = .F.
               Bit[9] = .F.
               Bit[10] = .F.
               Bit[11] = .F.
               Bit[12] = .F.
               Bit[13] = .F.
               Bit[14] = .F.
               Bit[15] = .F.


