@ME.FORMAT                                                        R
<< DOS Add-On Library>>
< General Information>
 General Information - Version 1.0  8/15/93

 Copyright (c) 1993 by Dean T. Miller
                       3220 Franklin Avenue
                       Des Moines  IA  50310-5131
                       (515) 277-8112
                       Compuserve: 75110,3417

 Please contact me to solve your difficult situations.

 This library adds DOS and other functions to the Clarion Database 
 Developer that can be useful to applications.  The functions are 
 listed by pressing 'Topics' on the help screen.

 These functions have been tested with CDD 3.004.

 The functions have not been tested with protected mode
 applications.  The functions which CANNOT work in protected mode
 are noted in the function descriptions.

< Adding DOS3 to an application>
  Adding DOS3 to an application

  The following procedure adds DOS3 (or any external library) to 
  your application.  Use keyboard or mouse to click where 
  appropriate.

  1. Load your application into CDD so the PROCEDURE WORKSHEET 
     shows.

  2. Press Alt-v, then 'm' to display the MODULE WORKSHEET.

  3. Press Insert to add a new module.
     Enter DOS3.LIB as the module name.
     Enter a description for your information.
     Check the EXTERNAL OBJECT MODULE button.
     Enter DOS3.INC as the 'MODULE structure include file.'
     Press Alt-o to save the new module definition.

  4. Press Ctrl-o to access the Application Properties screen.
     Press Alt-g to go to the Global Settings screen.
     Press Alt-u to open the Embedded Source screen.
     Select the data section. (Move the bar to 'data section' and
           press Enter.
     Enter "  INCLUDE('DOS3.CLI')" on the first line of the 
           screen.  
     Press Ctrl-x, Alt-o or whatever else is needed to save your 
           changes and get back to the MODULE WORKSHEET.

  5. Press Alt-n to open the PROJECT SETTINGS screen.
     Press Alt-l to open the ADVANCED MODULE SETTINGS screen.
     Select the line that shows 'DOS3.LIB' and press Enter.
     Change the module name to show '%clapfx%dos3.lib'.
     Press Alt-o three times to save the changes.

  You are now ready to use DOS3 functions in your application.

< Boot:                      CBoot(), WBoot()>
  Boot:                      CBoot(), WBoot()

  These functions will reboot the computer.
  CBoot() will boot as if you had pressed the reset button or just
        turned the computer on.  
  WBoot() will boot as if a Ctrl-Alt-Del 
        had been pressed.

  NOTE: These functions may not work with all BIOS.

  Prototype:
    CBoot()
    WBoot()

  Examples:

    CBoot()               ! Reset boot computer
    WBoot()               ! Ctrl-Alt-Delete boot computer

< Check Sum generator:       CheckSum()>
  Check Sum generator:       CheckSum()

  Updates a 2 byte validity code from the data at a specified
  address in memory.  The method used will detect a 1 to 10 bit 
  change in an 8K block of data 99.9994% of the time.  May be used 
  to verify the integrity of records, table files, etc.  This 
  procedure will NOT run in protected mode.

  Prototype:
    CheckSum(ULONG,USHORT,*BYTE,*BYTE)

  Parameters:
    CheckSum(MemoryAddress,NumberOfBytes,CkSum1,CkSum2)

    MemoryAddress = Absolute memory address in segment:offset
    NumberOfBytes = Byte count of area to be checksummed
    CkSum1,CkSum2 = Two bytes that contain the input and output
                    values of the checksum

  Examples:

Location    ULONG
            GROUP,OVER(Location)
Offset        USHORT
Segment       USHORT
            END !Group

BlockLength USHORT

CS1         BYTE
CS2         BYTE

NameString  STRING(55)

    CODE

    CS1 = 0                  ! Clear checksum values
    CS2 = 0
    CheckSum(Address(NameString),55,CS1,CS2)

                             ! CS1 and CS2 contain a checksum
                             ! for the data in NameString

    CS1 = 0                  ! Clear checksum values
    CS2 = 0
    Offset  = 0              ! absolute memory address - offset
    Segment = 0              !                         - segment
    BlockLength = 400h       ! (interrupt vector area)

    CheckSum(Location,BlockLength,CS1,CS2)

                             ! CS1 and CS2 contain a checksum
                             ! for the data at Location 0:0

                             ! NOTE: use CS1,CS2 from above 
    Offset  = 0              ! absolute memory address - offset
    Segment = 70h            !                         - segment
    BlockLength = 800h       ! (DOS standard driver area)

    CheckSum(Location,BlockLength,CS1,CS2)

                             ! CS1 and CS2 contain a checksum
                             ! for the data at Location 70:0 in
                             ! addition to location 0:0

< Binary to Hex string:      ToHex()>
  Binary to Hex string:      ToHex()

  Converts numbers to a string of hex characters.  Each byte of 
  the number is converted to two hexadecimal digits.

  Prototype:
    ToHex(STRING,BYTE,<BYTE>),STRING

  Parameters:
    ResultString = ToHex(InputData,InputLength,ByteSwapFlag)

    InputData    = 'String' to be converted to hex
    InputLength  = Number of input bytes (characters)
    ByteSwapFlag = True to swap bytes of input word for output
    ResultString = Output string

  Example:

NovArray    BYTE,DIM(6)              ! Novell Physical Ident
NovString   STRING(6),OVER(NovArray)
DispNode    STRING(12)               ! Result of conversion

Segment     USHORT                   ! A binary number
SegString   STRING(2),OVER(Segment)  ! Remapped to a string

SwapBytes   BYTE

    CODE

    SwapBytes = False            ! Convert Novell Physical ID

    DispNode = ToHex(NovString,LEN(NovString),SwapBytes)

    Segment = 112
    SwapBytes = True             ! Display 112 in hex (= 0070h)

    SHOW(1,1,'Segment Address:' & ToHex(SegString,2,SwapBytes) )

< Country - Convert Date:    ConvDate(), DefDate(), GetDateFormat()>
 Country - Convert Date:    ConvDate(), DefDate(), GetDateFormat()

  These functions automatically convert a Clarion date to/from a
    display format based on the DOS country data.  If country data
    is not set on computer, defaults to USA definitions.

  Prototypes:
    ConvDate(LONG),STRING
    DefDate(STRING),LONG
    GetDateFormat(*STRING),BYTE

  Parameters:
    StringDate = ConvDate(NumericDate)
        Converts Clarion date to string for a specific country.

    NumericDate = DefDate(StringDate)
        Converts string to Clarion date for a specific country.

    DateFormat = GetDateFormat(*DateSeparator)
        Returns the current date separator and date format.

    NumericDate   LONG        ! date in Clarion format
    StringDate    STRING(8)   ! display format
    DateSeparator STRING(1)   ! (i.e., '/' '-' '.' )
    DateFormat    BYTE        ! 0 = USA, 1 = Europe, 2 = Japan

  Examples:

USAdateN        LONG(70296)
USAdateS        STRING('6/15/93')
DispDate        STRING(8)
NumDate         LONG
Dformat         BYTE
DSeparator      STRING(1)

    CODE
            ! Using COUNTRY=049 in CONFIG.SYS (Germany)

    DispDate = ConvDate(USAdateN)       ! Dispdate = 15.06.93
    NumDate = DefDate(USAdateS)         ! NumDate = 70296
    DFormat = GetDateFormat(DSeparator) ! DFormat = 1
                                        ! DSeparator = '.'

< Country - Convert Time:    ConvTime(), DefTime(), GetTimeFormat()>
 Country - Convert Time:    ConvTime(), DefTime(), GetTimeFormat()

  These functions automatically convert a Clarion time to/from a
    display format based on the DOS country data.  If country data
    is not set on computer, defaults to USA definitions.

  Prototypes:
    ConvTime(LONG),STRING
    DefTime(STRING),LONG
    GetTimeFormat(*STRING),BYTE

  Parameters:
    StringTime = ConvTime(NumericTime)
        Converts Clarion time to string for a specific country.

    NumericTime = DefTime(StringTime)
        Converts string to Clarion time for a specific country.

    TimeFormat = GetTimeFormat(*TimeSeparator)
        Returns the current time separator and time format.

    NumericTime   LONG        ! time in Clarion format
    StringTime    STRING(8)   ! display format
    TimeSeparator STRING(1)   ! (i.e., ':' '.' or space)
    TimeFormat    BYTE        ! 0 = USA, 1 = Europe, 2 = Japan

  Examples:

USATimeN        LONG(70296)
USATimeS        STRING('6/15/93')
DispTime        STRING(8)
NumTime         LONG
Tformat         BYTE
TSeparator      STRING(1)

    CODE
            ! Using COUNTRY=049 in CONFIG.SYS (Germany)

    DispTime = Convtime(USATimeN)       ! DispTime = 15.06.93
    NumTime = DefTime(USATimeS)         ! NumTime = 70296
    TFormat = GetTimeFormat(TSeparator) ! TFormat = 1
                                        ! TSeparator = '.'

< Country - Currency:        GetCurrencyFormat()>
 Country - Currency:        GetCurrencyFormat()

  Gets the currency settings from the DOS country function.

  Prototype:
    GetCurrencyFormat(*STRING,*STRING,*STRING,*BYTE),BYTE

  Parameters:
    CurrCode = GetCurrencyFormat(Symbol,Thou,Dec,Places)

    Symbol   string(5)    ! Currency symbol - USA value = '$'
    Thou     string(2)    ! Thousands separator - USA value = ','
    Dec      string(2)    ! Decimal separator -   USA value = '.'
    Places   byte         ! USA value = 2
    CurrCode byte  ! 0 = currency symbol before amount, no spaces
                   ! 1 = currency symbol after amount, no spaces
                   ! 2 = currency symbol, one space, amount
                   ! 3 = amount, one space, currency symbol
                   ! 4 = symbol replaces decimal separator
  Examples:

< Directory scan:            SetDir(),NextDir()
 Directory scan:       SetDir(),NextDir()

  These functions scan a directory with date/time conversion.

  Prototype:
    SetDir(STRING,*GROUP,SHORT),SHORT
    NextDir(*GROUP),SHORT
    DirToQueue(STRING,QUEUE,BYTE,BYTE,BYTE,BYTE,BYTE),SHORT

  Parameters:

  Result = SetDir(Mask,Dir_Data,Attributes)
      Finds the first directory entry matching the Mask.

    Mask        STRING()    ! Drive, Path and wildcard file spec
    Dir_Data    GROUP       ! Defined in DOS3.CLI, holds
                            !   intermediate scan results
    Attributes  SHORT       ! File Attributes to use in scan
                            !    Defined in CLARION.EQU as:
                            !         FA_NORMAL    normal file
                            !         FA_RDONLY    Read only
                            !         FA_HIDDEN    Hidden file
                            !         FA_SYSTEM    System file
                            !         FA_LABEL     Volume label
                            !         FA_DIREC     Directory
                            !         FA_ARCH      Archive
                            !   Multiple attributes may be used
    Result      SHORT       ! SetDir/NextDir - No more entries

  Result = NextDir(Dir_Data)
      Finds the next directory entry after SetDir.

    Dir_Data    GROUP       ! Defined in DOS3.CLI, holds
                            !   intermediate scan results
    Result      SHORT       ! SetDir/NextDir - No more entries

  Example:

done            byte                    ! Holds the result flag
pattern         string('*.*')           ! File specification 

    Code

    Clear(dir_data)                 ! Initialize the data area
    done = SetDir(pattern,dir_data) ! Set the pattern and
                                    !   get the first file name
    if not done                     !   that matches the pattern
      loop until done               ! 0 means 'file name matched'
        do process_the_match        ! Do what you want
        done = NextDir(dir_data)    ! Keep processing matches
      .
    else
      do no_first_match                 ! Nothing matched
    .                                   ! Done indicates why


< Load queue with directory: DirToQueue()
 Load queue with directory:     DirToQueue()

  Loads a queue with current directory data.

  Prototype:
    DirToQueue(STRING,QUEUE,BYTE,BYTE,BYTE,BYTE,BYTE,BYTE),SHORT

  Parameters:

  Result = DirToQueue(Mask,FileQueue,Fld1,Fld2,Fld3,Fld4, |
                Compr,DirArrows)
      Scans a directory and fills a queue with the selected data.

    Mask        STRING()    ! Drive, Path and wildcard file spec

    FileQueue   QUEUE       ! Name of queue for entries

                            !   Queue record must be large enough
                            !   to hold desired fields.  Format:
                            !   STRING(1)     space at first char

                            !     STRING(12)  for filename/ext OR

                            !     STRING(8)      filename
                            !     STRING(1)
                            !     STRING(3)      file ext

                            !   STRING(1)
                            !   STRING(xx)    optional fields with
                            !         a 1 character space between
                            !   STRING(1)     space at last char

    Fld1        BYTE        ! Defines up to 4 optional fields to
    Fld2        BYTE        !   be included in queue record in 
    Fld3        BYTE        !   addition to the 12 character 
    Fld4        BYTE        !   filename field.
                            !   Each parameter may be 0 - 4.
                            !   They are:
                            !     0 = Fld not used
                            !     1 = Size        STRING(8)
                            !     2 = Date        STRING(8)
                            !     3 = Time        STRING(8)
                            !          Date/Time displayed in
                            !          current country format.
                            !     4 = Attributes  STRING(5)
                            !            characters 'DASHR'
    Compr       BYTE        ! True to separate filename into 2
                            !   sections: Name in cols 2-9, Ext
                            !   in cols 11-13 of queue record.
    DirArrows   BYTE        ! True to place up/down arrows to
                            !  indicate directory in queue col 11
    Result      SHORT       ! Returns ERRORCODE

  Example:

Files   QUEUE,PRE(Fil)
          STRING(1)         ! Space at front for readability,
Name      STRING(8)         ! could also be used for check marks.
          STRING(1)         ! A period '.' could be put here
Ext       STRING(3)
          STRING(1)         ! Spaces between fields for direct use
Attrib    STRING(5)         !   by the LIST box.
          STRING(1)
Date      STRING(8)         ! The Date and Time fields will be
          STRING(1)         !   entered using the current country
Time      STRING(8)         !   information.  Defaults to USA if
          STRING(1)         !   DOS Country is not present.
        .
OldPath STRING(64)
    CODE
    OldPath = PATH()        ! Save current path
    SETPATH('C:\')          ! Set to root directory
    SpinOn(25,40,112,3)     ! Displays spinner at line 25, col 40

    IF NOT DirToQueue('ss*.*',Files,4,2,3,0,True) ! Scan directory
      Sort(Files,Fil:Ext)   ! Sort by extension
    .
    SpinOff()               ! Restore character at spinner
    SETPATH(OldPath)        ! Restore orig path

! NOTE: Please remember the STRING(1) as the first byte of the
!       queue.

< Convert DOS date/time:     ToCTime(),ToCDate()
 Convert DOS date/time:     ToCTime(),ToCDate()

  These functions convert date/time from DOS to Clarion format.

  Prototype:
    ToCTime(USHORT),LONG
    ToCDate(USHORT),LONG

  Parameters:

  Time = ToCTime(DOStime)
     Converts DOS time format (in Dir_Data) to Clarion time format

    DOStime     USHORT      ! defined in Dir_Data as ddt:time
    Time        LONG        ! Clarion time count


  Date = ToCDate(DOSdate)
     Converts DOS date format (in Dir_Data) to Clarion date format

    DOSdate     USHORT      ! defined in Dir_Data as ddt:date
    Date        LONG        ! Clarion date count

  Examples:

    DateMade = ToCDate(ddt:date)
    TimeMade = ToCTime(ddt:time)

< Manipulate path string:    AdjPath()
 Manipulate path string:    AdjPath()

  Adds or Removes a directory name to a path string

  Prototype:
    AdjPath(STRING,STRING,BYTE),STRING

  Parameters:

  NewPath = AdjPath(OldPath,ChangeString,BSlashFlag)

    OldPath       STRING(64)  ! Original path to change
    ChangeString  STRING(8)   ! Addition or 
                              !  '..' to remove directory
    NewPath       STRING(64)  ! Result path
    BSlashFlag    BYTE        ! 1 = ending backslash, 0 = none

  Example:

NewPath      STRING(64)                 ! Variable to receive data
ChangeString STRING('NewDir')           ! A directory name
OrigPath     STRING('C:\CLARION3\TEST') ! Current path

  CODE

  NewPath = AdjPath(OrigPath,'..',0)    ! Remove 'TEST' from path
  NewPath = AdjPath(NewPath,ChangeString,0) ! Add 'NewDir' to path

< Display shortened path:    TruncPath()
 Display shortened path:    TruncPath()

  Produces a shortened path for display purposes in either
     C:\DICTYONE\...\ENDDICTY   or
     C:\DICTYONE\...\PREVDIR\ENDDICTY  formats

  Prototype:
    TruncPath(STRING,SHORT),STRING

  Parameters:

  ShortPath = TruncPath(Path,MaxLength)

    ShortPath     STRING(24)  ! Result path
    Path          STRING(64)  ! Original path to display
    MaxLength     SHORT(24)   ! Size of ShortPath
  NOTE: Suggested minimum size for ShortPath is 24 characters

  Example:

ShortPath     STRING(24)      ! Result path
Path          STRING(64)      ! Original path to display
MaxLength     SHORT(24)       ! Size of ShortPath

    CODE

    ShortPath = TruncPath(Path,MaxLength)

< Scan for active drives:    ScanDrives()
 Scan for active drives:    ScanDrives()

  Returns a string of active drive letters
    Does not test drives A and B.  Any SUBST drives, ramdisk
    and network letters will be included.

  Prototype:
    ScanDrives(),STRING       ! Return active drive letters

  Parameters:

  DLetters = ScanDrives()

    DLetters      STRING(26)  ! Active drive letters

  Example:

DLetters      STRING(26)  ! Active drive letters

    CODE

    Dletters = ScanDrives()

< Directories:               MakeDir(), RemoveDir()>
 Directories:               MakeDir(), RemoveDir()

  Create or Delete a directory

  Prototype:
    MakeDir(STRING),SHORT
    RemoveDir(STRING),SHORT

  Parameters:
    Result = MakeDir(NewPath)
    Result = RemoveDir(OldPath)

    NewPath    STRING(..)       ! Directory to be added
    OldPath    STRING(..)       ! Directory to be removed
    Result     SHORT            ! 0 = successful, non-zero = error

  Examples:

< File attributes:           GetFAttr(), SetFAttr()>
 File attributes:           GetFAttr(), SetFAttr()

  Read or Set Attributes for a file.  The attribute codes are:
     1  =  Read-Only
     2  =  Hidden
     4  =  System
    20h =  Archive

  Prototype:
    SetFAttr(string,byte),short         ! Set file attributes
    GetFAttr(string),short              ! Get file attributes

  Parameters:
    SetFAttr(FileSpec,NewAttrib),Result
    GetFAttr(FileSpec),OldAttrib

    FileSpec    STRING(..)      ! Path and Filename
    NewAttrib   BYTE            ! New value for ALL attributes
    OldAttrib   SHORT           ! Current file attributes
                                ! Error when > 255
    Result      SHORT           ! 0 = successful, non-zero = error

  Examples:

FileSpec        STRING('C:\CL3\CLARION3.HLP')
Attrib          SHORT
Result          SHORT
    CODE

    Attrib = GetFAttr(FileSpec)  ! Get attributes
    IF Attrib < 255
       Result = SetFAttr(FileSpec, BOR(Attrib,1) ) ! Set Read Only
    .
    IF Result > 255 then do error_code.

    NOTE: PLEASE DO NOT TRY THIS AT HOME USING 'CLARION3.HLP'<G>.
CDD seems to change the file 'CLARION3.HLP' so making it read-only
could break your computer.

< File Test:                 FileExists()>
 File Test:                 FileExists()

  Tests for the existence of the named path and filename.

  Prototype:
    FileExists(STRING),SHORT

  Parameters:
    FileExists(FileSpec),Result

    FileSpec    STRING(64)      ! Path and Filename
    Result      SHORT           ! 1 = Exists, 0 = can't find

  Examples:

FileSpec        STRING('C:\CL3\CLARION3.HLP')
Result          SHORT
FromFile        FILE,DRIVER('DOS'),NAME(FileSpec)
Record            RECORD
                    BYTE,DIM(1024)
                . .
    CODE

    IF FileExists(FileSpec)
      COPY(FromFile,'A:\')
    .

< Program Segment Prefix:    GetPSP()>
 Program Segment Prefix:    GetPSP()

  Get the address of the Program Segment Prefix for the current
  program.  See an advanced DOS programming manual.

  Prototype:
    GetPSP(),ushort

  Parameters:
    GetPSP(),SegmentAddress

    SegmentAddress  USHORT      ! Segment of the Program Segment
                                !    Prefix,  Offset is 0

< Scroll with Attributes:    ScrolAtr()>
 Scroll with Attributes:    ScrolAtr()

  Prototype:
    ScrolAtr(byte,byte,byte,byte,short) ! Scroll with attributes

  Parameters:
    ScrolAtr(Row,Col,Rows,Cols,Lines)

    Row          BYTE        ! Top row of display to be scrolled
    Col          BYTE        ! Left column of display to scroll
    Rows         BYTE        ! Number of rows in scroll area
    Cols         BYTE        ! Number of columns in scroll area
    Lines        SHORT       ! Number of blank lines
                             !   Direction:  - up, + down

  Example:

  ndx            BYTE
  winrow         BYTE
  wincol         BYTE
  winrows        BYTE
  wincols        BYTE

  screen    SCREEN(18,63),PRE(scr),SHADOW,WIPE,CUA,COLOR(23)
                          REPEAT(10),INDEX(ndx)
              ROW(3,4)      POINT(1,40),USE(?point),COLOR(49,81)
  f1            COL(4)      STRING(@s5),COLOR(112)
  f2            COL(10)     STRING(@s20),COLOR(112)
            .             .


    CODE
    ndx = 1                     ! Set to first point row
    winrow = row(?point)        ! Save row and
    wincol = col(?point)        ! column positions of point field
    winrows = rows(?point)      ! Rows in point area
    wincols = cols(?point)      ! Columns in point area
    setcolor(17h)                       ! make a different color
    paint(winrow+5,wincol,1,wincols)    !   in the point area
    setcolor                            ! go back to normal color
    scrolatr(winrow,wincol,winrows,wincols,1) ! Scroll down 1 row

< Spool to printer:          Spool()>
 Spool to printer:          Spool()

  Copies a file to the DOS PRINT queue.  The PRINT command must be
  executed before the program containing the Spool is run.

  Prototype:
    Spool(string),short           ! Spool file to printer

  Parameters:
    Spool(FileSpec),ReturnCode

    FileSpec    STRING(64)     ! Name (and Path) of file to spool
    ReturnCode  SHORT          ! Place to hold returned error code

  Example:

  Return        SHORT          ! Error code (0 = good)
    CODE
    Return = Spool('c:\reports\text.doc')

< Display Activity Spinner:  Spin()>
 Display Activity Spinner:  Spin()

  Display a spinning 'activity indicator' in one column of
  the screen.  The characters used in the spinner are: \ | / -

  Prototype:
    SpinOn(byte,byte,byte,<byte>)  ! Set up Spinner
    SpinOff()                      ! Restore screen character
    Spin()                         ! Rotate spinner

  Parameters:
    SpinOn(Row,Column,Colour,SpeedDivisor)
    SpinOff()
    Spin()

    Row           BYTE         ! Row number on DISPLAY SCREEN
    Column        BYTE         ! Column number on DISPLAY SCREEN
    Colour        BYTE         ! Color number
    SpeedDivisor  BYTE         ! Rotates the spinner every
                               !   SpeedDivisor times
                               !   Default: 1 (every time)
  Example:

  ndx             short
    CODE
    SpinOn(12,40,112,3)        ! Will display a spinner at
                               !   row 12, column 40 using
                               !   color number 122, 
                               !   rotating every third
                               !   entry into the routine.
    Loop ndx = 1 to 1000
      Spin()                   ! Display spinner
    .
    SpinOff()                  ! Restores original screen char

