C5_DOSERROR

 DOSERROR()
 Return the last DOS error number
------------------------------------------------------------------------------
 Syntax

     DOSERROR([<nNewOsCode>]) --> nOsCode

 Arguments

     <nNewOsCode>, if specified, alters the value returned by DOSERROR().
     The value must be a numeric value that reflects a DOS error number.

 Returns

     DOSERROR() returns the DOS error number as an integer numeric value.

 Description

     DOSERROR() is an error function that returns the last DOS error code
     associated with an activation of the runtime error block.  When a
     runtime error occurs, the DOSERROR() function is set to the current DOS
     error if the operation has an associated DOS error.  The function value
     is retained until another runtime error occurs.  If the failed operation
     has no associated DOS error, the DOSERROR() returns zero.  With low-
     level file functions, FERROR() returns the same value as DOSERROR().

     Through use of the optional <nNewOsCode>, you may customize to the
     reporting activation the returned value for any DOS error.

     For a complete list of DOS error numbers and accompanying descriptions,
     refer to the Error Messages and Appendices Guide.

 Files   Library is CLIPPER.LIB.

See Also: ERRORBLOCK() FERROR()



C5_DISPOUT

 DISPOUT()
 Write a value to the display
------------------------------------------------------------------------------
 Syntax

     DISPOUT(<exp>, [<cColorString>]) --> NIL

 Arguments

     <exp> is the value to display.

     <cColorString> is an optional argument that defines the display
     color of <exp>.  If unspecified, <exp> is displayed as the standard
     color of the current system color as defined by SETCOLOR().
     <cColorString> is a character expression containing the standard color
     setting.  You can specify a literal color setting, if you enclose it in
     quote marks.

 Returns

     DISPOUT() always returns NIL.

 Description

     DISPOUT() is a simple output function that writes the value of a single
     expression to the display at the current cursor position.  This function
     ignores the SET DEVICE setting; output always goes to the screen.  You
     can only use this function within a procedure or function.

 Examples

     .  This example performs screen output at a specified location in
        different colors.  Note how the cursor position is saved and restored
        using ROW(), COL(), and SETPOS():

        PROCEDURE Showit
           LOCAL nRow, nCol
           ? nCol := COL()            // save original
           ?? nRow := ROW()            // cursor position

           INKEY(2)

           SETPOS(nRow, nCol)
           DISPOUT("This is a test of DISPOUT()")
           ? COL()                     // display current
           ?? ROW()                     // cursor position

           INKEY(2)

           SETPOS(nRow, nCol)
           DISPOUT(space(26))         // clear original position
           SET DEVICE TO PRINTER      // ignores SET DEVICE

           SETPOS(nRow, nCol)         // display at
           DISPOUT("           all through")
                                      // original position

           RETURN

 Files   Library is CLIPPER.LIB.

See Also: COL() OUTSTD() QOUT() ROW() SETCOLOR() SETPOS()



C5_DISPEND

 DISPEND()
 Display buffered screen updates
------------------------------------------------------------------------------
 Syntax

     DISPEND() --> NIL

 Returns

     DISPEND() always returns NIL.

 Description

     DISPEND() is a screen function that informs the Clipper display
     output system that the application has finished performing a series of
     display operations.

     DISPEND() is used with DISPBEGIN() so the display output system can
     buffer display updates.  This can be important for applications in which
     complex screen displays are slow and the appearance of performance is
     desired.

 Examples

     .  This example buffers screen output, updates the screen, and
        then displays the buffered screen output:

        DISPBEGIN()            // Start screen buffering
        //
        SETPOS(10, 10)
        DISPOUT("A display update")
        SETPOS(11, 10)
        DISPOUT("Another display update")
        //
        DISPEND()               // Display buffered screen data

 Files   Library is CLIPPER.LIB.

See Also: DISPBEGIN()



C5_DISPCOUNT

 DISPCOUNT()
 Return the number of pending DISPEND() requests
------------------------------------------------------------------------------
 Syntax

     DISPCOUNT() --> nDispCount

 Returns

     DISPCOUNT() returns the number of DISPEND() calls required to restore
     the original display context.

 Description

     You can use DISPCOUNT() to determine the current display context.
     Clipper uses display contexts to buffer and to supervise screen
     output operations.

     Each call to DISPBEGIN() defines a new display context.  Output to the
     display context is suppressed until a matching DISPEND() statement
     executes.

     Since you may nest DISPBEGIN() calls, use DISPCOUNT() to determine
     whether there are pending screen refresh requests.

 Examples

     .  This example saves the setting of DISPCOUNT(), then releases
        all pending display contexts before writing to the screen:

        PROCEDURE ForceDisplay(cExp)
           LOCAL nSavCount

        nSavCount := DISPCOUNT()

        //  Discard pending display contexts
        DO WHILE ( DISPCOUNT() > 0)
           DISPEND()

        ENDDO

        DISPOUT(cExp)

        //  "Rewind" the current display context
        DO WHILE (DISPCCOUNT() < nSavCount )
           DISPBEGIN()
        ENDDO

        RETURN

 Files   Library is CLIPPER.LIB.

See Also: DISPBEGIN() DISPEND()



C5_DISPBOX

 DISPBOX()
 Display a box on the screen
------------------------------------------------------------------------------
 Syntax

     DISPBOX(<nTop>, <nLeft>, <nBottom>, <nRight>,
        [<cnBoxString>], [<cColorString>]) --> NIL

 Arguments

     <nTop>, <nLeft>, <nBottom>, and <nRight> define the
     coordinates of the box.  DISPBOX() draws a box using row values from
     zero to MAXROW(), and column values from zero to MAXCOL().  If <nBottom>
     and <nRight> are larger than MAXROW() and MAXCOL(), the bottom-right
     corner is drawn off the screen.

     <cnBoxString> is a numeric or character expression that defines the
     border characters of the box.  If specified as a numeric expression, a
     value of 1 displays a single-line box and a value of 2 displays a
     double-line box.  All other numeric values display a single-line box.

     If <cnBoxString> is a character expression, it specifies the characters
     to be used in drawing the box.  This is a string of eight border
     characters and a fill character.  If <cnBoxString> is specified as a
     single character, that character is used to draw the whole box.

     If this argument is not specified, a single-line box is drawn.

     <cColorString> defines the display color of the box that is drawn.
     If not specified, the box is drawn using the standard color setting of
     the current system color as defined by SETCOLOR().

 Returns

     DISPBOX() always returns NIL.

 Description

     DISPBOX() is a screen function that draws a box at the specified display
     coordinates in the specified color.  If you specify <cnBoxString>,
     DISPBOX() draws a box on the screen using configurable border and fill
     characters.  DISPBOX() draws the box using <cnBoxString> starting from
     the upper left-hand corner, proceeding clockwise and filling the screen
     region with the ninth character.  If the ninth character is not
     specified, the screen region within the box is not painted.  Existing
     text and color remain unchanged.

     In cases where cnBoxString respects Clipper conventions, the behavior
     of DISPBOX() is unchanged.  The behavior of this function can easily be
     modified to take advantage of graphic mode.  For example, you can
     replace the standard window frames using single or double lines with new
     graphical frames that have an impressive 3-D look.  Simply replace the
     cBoxString parameter using the following:

     CHR(2) + CHR(nColor+1) // draws a box of thickness 16x8x16x8
     CHR(3) + CHR(nColor+1) // draws a box of thickness 8x8x8x8
     CHR(4) + CHR(nColor+1) // draws a box of thickness

                            // 16x16x16x16
     CHR(5) + CHR(nColor+1) // draws a box of thickness 16x8x8x8

     Note that <nColor> is a numeric color representation.  You must add 1 to
     this value.

     In general, CHR(2) + CHR(nColor+1) can be used instead of Clipper's
     B_SINGLE or B_DOUBLE defines.

     Clipper graphics comes with two #defines LLG_BOX_GRAY_STD and
     LLG_BOX_GRAY_SQUARE to allow gray (nColor=7) boxes of width 16x8 or
     16x16.

     You can completely customize the box by passing chr(1) + ... as the
     first parameter:

     CHR(1)             + ;  // Box entirely defined
     CHR(nBackColor+1)  + ;  // Color used as background fill
     CHR(nLightColor+1) + ;  // Color used to lighten the frame
     CHR(nDarkColor+1)  + ;  // Color used to darken the frame
     CHR(nWidthUp)      + ;  // Thickness of upper edge of box
     CHR(nWidthRight)   + ;  // Thickness of right edge of box
     CHR(nWidthDown)    + ;  // Thickness of lower edge of box
     CHR(nWidthLeft)         // Thickness of left edge of box

     After DISPBOX() executes, the cursor is located in the upper corner of
     the boxed region at <nTop> + 1 and <nLeft> + 1.  ROW() and COL() are
     also updated to reflect the new cursor position.

     Note that Box.ch, located in \CLIP53\INCLUDE, provides constants for
     various border configurations.

 Notes

     The number of colors available depends on the current video mode setting
     ( SET VIDEOMODE ).

 Examples

     .  This code example displays a double-line box using a numeric
        value to specify the box border:

        #define B_SINGLE   1
        #define B_DOUBLE   2
        //
        DISPBOX(1, 1, 10, 10, B_DOUBLE, "BG+/B")

     .  This example displays a single-line top and double-line side
        box by specifying border characters with a manifest constant defined
        in Box.ch:

        #include "Box.ch"
        //
        DISPBOX(1, 1, 10, 10, B_SINGLE_DOUBLE, "BG+/B")

     .  This example displays a box with a 3-D look.  It can be used
        for graphic mode:

        // Display a box with a 3D look of constant width 16x16x16x16
        DISPBOX( nTop, nLeft, nBottom, nRight, LLG_BOX_GRAY_SQUARE )
        // Write some transparent text in the 3D frame
        GWRITEAT(  nLeft * GMODE()[LLG_MODE_FONT_COL] ,;
        nTop  * GMODE()[LLG_MODE_FONT_ROW] ,;
        "This is some Text...",;
        4,;
        LLG_MODE_SET; )

 Files   Library is LLIBG.LIB, header file is Llibg.ch.

See Also: GFRAME() GMODE() SET VIDEOMODE

 

C5_DISPBEGIN

 DISPBEGIN()
 Begin buffering screen output
------------------------------------------------------------------------------
 Syntax

     DISPBEGIN() --> NIL

 Returns

     DISPBEGIN() always returns NIL.

 Description

     DISPBEGIN() is a screen function that informs the Clipper display
     output system that the application is about to perform a series of
     display operations.

     Use DISPBEGIN() with DISPEND() to allow the display output system to
     buffer display updates.  Display output which occurs after DISPBEGIN()
     but before DISPEND() is allowed to accumulate in internal buffers.  When
     DISPEND() executes, any pending updates appear on the physical display.
     This is useful in applications where complex screen displays are slow
     and the appearance of performance is desired.

     DISPBEGIN() and DISPEND() calls are optional.  They are not required for
     normal output.

 Notes

     .  Nested calls: DISPBEGIN() calls are nested internally.  If
        several DISPBEGIN() calls occur, buffering is allowed until a
        corresponding number of DISPEND() calls occur.

     .  Guaranteed operations: Display updates performed between
        DISPBEGIN() and DISPEND() are not guaranteed to be buffered--some
        updates may become visible before DISPEND() is called.  However, all
        updates are guaranteed to be visible after the closing call to
        DISPEND().

     .  Terminal operations: Terminal input operations such as INKEY()
        or READ should not be performed between DISPBEGIN() and DISPEND().
        Doing this may cause input or display output to be lost.

     .  Incompatible operations: Display output by other than the
        Clipper display functions (e.g., by add-on libraries or by DOS via
        OUTSTD(), etc.) may not be compatible with DISPBEGIN() and DISPEND().
        Output may be lost.

 Examples

     .  This example buffers screen output, updates the screen, and
        then displays the buffered screen output:

        DISPBEGIN()            // Start screen buffering
        //
        SETPOS(10, 10)
        DISPOUT("A display update")
        SETPOS(11, 10)
        DISPOUT("Another display update")
        //
        DISPEND()               // Display buffered screen data

 Files   Library is CLIPPER.LIB.

See Also: DISPEND()



C5_DISKSPACE

 DISKSPACE()
 Return the space available on a specified disk
------------------------------------------------------------------------------
 Syntax

     DISKSPACE([<nDrive>]) --> nBytes

 Arguments

     <nDrive> is the number of the drive to query, where one is drive A,
     two is B, three is C, etc.  The default is the current DOS drive if
     <nDrive> is omitted or specified as zero.

 Returns

     DISKSPACE() returns the number of bytes of empty space on the specified
     disk drive as an integer numeric value.

 Description

     DISKSPACE() is an environment function that determines the number of
     available bytes remaining on the specified disk drive.  It is useful
     when COPYing or SORTing to another drive to determine if there is enough
     space available before initiating the operation.  You may also use
     DISKSPACE() with RECSIZE() and RECCOUNT() to create a procedure to back
     up database files.

     DISKSPACE() ignores the SET DEFAULT drive setting.

 Examples

     .  This example is a user-defined function that demonstrates the
        use of DISKSPACE() to back up a database file to another drive:

        FUNCTION BackUp( cTargetFile, cTargetDrive )
           LOCAL nSpaceNeeded, nTargetDrive
           //
           nSpaceNeeded := INT((RECSIZE() * ;
              LASTREC()) + HEADER() + 1)
           nTargetDrive := ASC(UPPER(cTargetDrive)) - 64
           //
           IF DISKSPACE(nTargetDrive) < nSpaceNeeded
              RETURN .F.
           ENDIF
           COPY TO (cTargetDrive + ":" + cTargetFile)
           //
           RETURN .T.

 Files   Library is EXTEND.LIB.


See Also: LASTREC() LUPDATE() RECSIZE()