Introduction Date/Time Functions


     This section contains functions that make many date computations easier
     to perform.  Date-type values have been a feature of the xBASE language
     standard, and is preserved in Clipper.  In spite of this, it is
     always necessary to develop UDFs to execute certain technical financial
     computations.  Clipper Tools offers an alternative that not only
     spares you the work of writing a UDF, but also provides implementation
     in Assembler to guarantee fast execution.

     This chapter also contains clock time functions.  These include time
     changes, time span computations, time control of loops, and memory-
     resident clock display.

     Please note that valid date tests are already carried out in Clipper.
     Clipper internal date tests cannot be canceled, so it is impossible
     to implement an individual UDF for error handling , if there is an
     invalid date.

     Clipper always replaces an invalid date with a null date.  These
     internal tests are carried out by keyboard input, as well as by CTOD()
     allocation.  For this reason, there are no examples with invalid dates
     in the date function descriptions.  Rather, the result of a function
     with a null date is shown.

Introduction Printer Functions


     This chapter discusses printer output.  Although Clipper handles
     printer errors with an error trap, it is always better to avoid them
     completely.  As a result, error traps for printer output will not become
     superfluous, since errors also occur during output.  You can also
     determine a wide variety of information, such as the number of available
     printers or the printer status.

     This chapter also describes functions that support DOS print spoolers.
     To implement these functions, prior to starting the respective
     application, you must run the DOS PRINT program to make the print
     spooler memory resident.  Files can then be exclusively passed from a
     program to the spooler.  However, you must first reroute your print
     output to a file (SET PRINTER TO <file>), before you can output it in
     the background.

    Since this section is about DOS-TEXT mode programming, considered as 
    obsolete and details skipped.


Introduction Disk Utilities

Fundamental to the disk functions

 Fault tolerance and more

     One of the biggest problems in stable application development is how to
     handle errors.  Errors that occur during hard or floppy disk operations
     are especially frustrating.  You may also encounter critical errors,
     which disable the program or operating system.  The result, known to all
     Clipper programmers, are the DOS error choices:  (A)bort, (R)etry,

 Avoiding Errors

     Error trap functions allow you to react to this type of error, but a
     strategy to avoid them completely is better.  Therefore, Clipper
     Tools includes functions to make it easier to handle floppy and hard
     disk errors.

 Backup Systems

     Backup systems, another component of the Clipper application, are
     also discussed in this chapter.  The recursive FILESEEK() system, which
     allows you to format disks with DISKFORMAT(), is particularly useful.
     Complete directories can be scanned recursively, and queries regarding
     detailed information for every file can be made.  The ideal time to
     carry out this process is during source and target drive back ups,
     because only the information that has changed is copied.

     To avoid the annoying and not particularly fault-tolerant "RUN FORMAT",
     you can format the file disks directly from the application in all
     commonly available formats.  Since the control UDF for DISKFORMAT() uses
     a concept similar to DBEDIT(), you can display the format procedures on
     the screen as desired.

     You can also determine a good deal of varied information about disk
     drives, files, and other things.  This information far exceeds that of
     the FILESEEK() system.

 File Attributes

     Following is the coding for each function where a file can be

     Table 1:
     Value   Symb. constants     Assigned attribute
     0       FA_NORMAL
     1       FA_READONLY         READ ONLY
     2       FA_HIDDEN           HIDDEN
     4       FA_SYSTEM           SYSTEM
     8       FA_VOLUME           VOLUME
     16      FA_DIRECTORY        DIR
     32      FA_ARCHIVE          ARCHIVE

     If multiple attributes are implemented for a file, then the table
     values are added accordingly.  For example, if the HIDDEN and SYSTEM
     attributes are implemented, the function must pass a 6 (2 + 4) as the
     attribute mask.

     All file attributes do not behave the same.  To initiate a file into the
     process, you must explicitly specify the HIDDEN, SYSTEM, VOLUME and DIR
     attributes.  However, if either no attribute, R/O, or ARCHIVE is
     implemented with a file, it does not matter which value is passed.
     These rules for attribute handling are grounded in DOS, which compares
     the specified value with the actual file attributes in this way.  Since
     in some circumstances this may lead to problems, the FILESEEK() function
     allows you to switch on an additional EXACT ATTRIBUTE MATCHING.

 Share Modes

     For DOS version 3.0 or higher, if a function uses the DOS OPEN FILE call
     internally, it must pass a share mode.  This way, one station determines
     how all other stations in the network can access the open file. This is
     valid for as long as the file remains open.  The following variations

     Table 3:  Share Mode
     Code    Symb. constants     Share Modes
     0       SHARE_COMPAT        Compatibility mode.  Here, DOS or the
                                 network software itself, determines the
                                 share mode.  In Novell networks, the
                                 SHAREABLE attribute plays an important role
                                 in this relationship.
     1       SHARE_EXCLUSIVE     Both read and write by other programs are
                                 locked out
     2       SHARE_DENYWRITE     Write by other programs are locked out
     3       SHARE_DENYREAD      Read by other programs are locked out
     4       SHARE_DENYNONE      Not locked.  Read and write by other
                                 programs is allowed

     With the basic setting, all files are opened in the compatibility mode
     (relating to older DOS).  As a rule, the share mode depends on file
     attributes or the network software setting.

     Also in this chapter is the SETSHARE() function, which determines the
     share mode that enables all Clipper Tools functions to open a file.
     Clipper commands or functions are not affected in any way.


     Use the CSETSAFETY() function as a safety switch to protect existing
     files from unwanted overwriting during file operations with Clipper
     Tools functions.  You will find this function in the chapter on Switches
     and Status Information, since it concerns all Clipper Tools file

Introduction Video Functions


 Working With Video Functions

     This module discusses video functions that are either directly or
     indirectly concerned with the screen.  Included are all functions that
     deal with such screen adapters as CGA, EGA and Hercules.  Different
     modes on various adapters are supported, such as a 40-column CGA, a 43-
     line EGA, or a 50-line VGA.


     Many of the functions in this chapter depend on setting the DSETWINDOW()
     switch.  This switch determines if the screen output of external
     programs, as well as DOS, are redirected to a window.
     Clipper Tools output functions are also valid as external.  If the
     default setting in DSETWINDOW() is .T. or on, this rerouting is carried
     out.  Some functions will then return inaccurate, or at the very least,
     different results.  Examples of this are ISANSI() or NUMCOL()


     Many of the functions in this module work with color attributes
     designated as parameters.  These arguments are carried out in three
     different ways:

     A numeric value, which corresponds to a combined color attribute
     (e.g., 7).

     A string in the "NN/NN" form, with two specified numeric values (e.g.,

     A string in the "CC/CC" form, with two specified attributes are
     designated in the form Clipper requires (e.g., "W/N").

     With many functions, the attribute returns a combined numeric value.
     Attributes for the foreground and background are tied together this way.

     Color attributes are constructed as follows:

     Bit                8 7 6 5        4 3 2 1
     Attribute          * R G B        + R G B
           _ _ _ _ _ _  /   _ _ _ _ _ _

           Background   /   Foreground

     Each attribute consists of four bits, which represent a value in the
     range of 0 to 15.  Therefore, there are a total of 16*16, or 256,
     different values from 0 to 255.  These numeric values can be changed
     into the "nn/nn" format, that can be used under Clipper with the
     NTOCOLOR function.  However, it is possible to directly influence this
     combined attribute value.  The following examples show this and relate
     back to the chapter on number and bit manipulation:

     NUMOR( nattr, 128)    // Flashing on
     NUMAND(nattr, 127)    // Flashing off
     NUMXOR(nattr, 128)    // Change flashing
     NUMOR(nattr,  8)      // High intensity on
     NUMAND(nattr, 247)    // High intensity off
     NUMXOR(nattr,  8)     // Switch high intensity

 Special Parameter Type

     With many functions, a parameter may be of the <mIcCharacter|nCharacter>
     type (e.g., an individual character).  This can occur in two different

     Numerically, as the ASCII code of the desired character (e.g., 7).

     Alphanumeric as the character (e.g., ":").

     Because of this, you must not use the CHR() function to change special


     Some of the Clipper Tools functions use a standard attribute and
     character to  delete lines or screen areas.  This attribute is described
     as CLEARA; the character as CLEARB.  You can query both CLEARA and
     CLEARB with the corresponding functions.  At the same time, certain
     preset values are in effect for CLEARA and CLEARB.  The attribute "W/N"
     is the standard preset for CLEARA, while CHR(255) is the character used
     for CLEARB.  If you use this character for CLEARB, it fills the
     background with the corresponding color for every deletion on every
     screen adapter.

     Use the following functions to set standard values for CLEARA and


     If you use the SETCLEARx() functions in conjunction with the
     corresponding parameters (<Attribute> or <Character>), the currently
     existing default value is replaced by a parameter.

 Clipper Functions and Commands Which Delete

     If you use the Clipper Extended Drivers, CHR(255) is used instead of
     a space for all Clipper functions and commands that delete the screen
     in one way or another (see CLEARB).  A CHR(255) is helpful on many
     screen adapters, since in contrast to a space, you can assign it a
     color.  Then, the screen will not appear so fuzzy.

     More precisely, the functions and commands concerned always use the
     delete character set by SETCLEARB(), which uses CHR(255) as the default
     setting.  If you want to use a space to clear in Clipper or
     Clipper Tools, insert a SETCLEARB(32) into the program.

     Re-implement a space for clear:

        CLEAR         // The affected Clipper command

 Video Modes

     Occasionally, there is some confusion about video modes.  You will not
     be able to work in EGA mode just because your computer has an EGA
     adapter built into it.  By the same token, you will not get either EGA
     or VGA modes, if you do not work with graphics.

 EGA43 / VGA50 / VGA28, etc.

     In this section, the concern is not to just get a mode "hardwired"' into
     a card, but for Clipper Tools it is to generate corresponding fonts
     and other settings.  For these reasons, the GETMODE() and GETSCRMODE()
     functions generate their own values that are greater than 255.

     For example, changes to the screen mode concerned with line count can be
     combined with a 40-column mode:

     EGA43()          // 43 lines and 40 columns

 Video Functions and Windows

     You cannot implement functions that change the base address for screen
     memory while windows are open.  This includes all mode changes, as well


      Since this section is about DOS-TEXT mode programming, considered as obsolete and details skipped.

Introduction Number and Bit Manipulation

Introduction CT Number and Bit Manipulation

This module discusses number and bit manipulation. Specifically, the numeric section deals with conversions between two different number systems, and the creation of random numbers.

The bit manipulation section covers such required binary operations as AND, OR, XOR, and NOT, and how to test, set and clear bits. The NUMLOW() and NUMHIGH() functions are important for CA-Clipper Tools functions that take two 8-bit values and return them as combined 16-bit numbers. An example is the GETCURSOR() function from the Extended Drivers module.

Many of the functions in this module have a <value> parameter type. In this case, a number can be in the range of 0 to 65535 (or 4 294 967 295) and/or a hexadecimal string in the range of “0000” to “FFFF” (or “FFFFFFFF”).

CT Number and Bit Manipulation Functions