C5_CURDIR

 CURDIR()
 Return the current DOS directory
------------------------------------------------------------------------------
 Syntax

     CURDIR([<cDrivespec>]) --> cDirectory

 Arguments

     <cDrivespec> specifies the letter of the disk drive to query.  If
     not specified, the default is the current DOS drive.

 Returns

     CURDIR() returns the current DOS directory of the drive specified by
     <cDrivespec> as a character string without either leading or trailing
     backslash (\) characters.

     If an error occurs, or the current directory of the specified drive is
     the root directory, CURDIR() returns a null string ("").

 Description

     CURDIR() is an environment function that gives you the name of the
     current DOS directory, ignoring the SET DEFAULT and SET PATH settings.

 Examples

     .  These examples illustrate various CURDIR() results:

        ? CURDIR("E:")     // Result: null string--root directory
        ? CURDIR("C")      // Result: CLIP53\SOURCE
        ? CURDIR("C:")     // Result: CLIP53\SOURCE
        ? CURDIR()         // Result: null string--root directory
        ? CURDIR("A")      // Result: null string--drive not ready

     .  This example changes the current DOS directory to a new value
        if it does not match a specified directory:

        IF CURDIR("C:") != "CLIP53\SOURCE"
           RUN CD \CLIP53\SOURCE
        ENDIF

 Files   Library is EXTEND.LIB, source file is SOURCE\SAMPLE\EXAMPLEA.ASM

See Also: FILE()

C5_CTOD

 CTOD()
 Convert a date string to a date value
------------------------------------------------------------------------------
 Syntax

     CTOD(<cDate>) --> dDate

 Arguments

     <cDate> is a character string consisting of numbers representing the
     month, day, and year separated by any character other than a number.
     The month, day, and year digits must be specified in accordance with the
     SET DATE format.  If the century digits are not specified, the century
     is determined by the rules of SET EPOCH.

 Returns

     CTOD() returns a date value.  If <cDate> is not a valid date, CTOD()
     returns an empty date.

 Description

     CTOD() is a character conversion function that converts a character
     string to a date.  To initialize an empty date for date entry, specify
     <cDate> as a null string (""), SPACE(8), or "  /  /  ".

     CTOD() is used whenever you need a literal date value.  Some examples
     are:

     .  Initializing a variable to a date value

     .  Specifying a literal date string as an argument of a RANGE
        clause of @...GET

     .  Specifying a literal date string in order to perform date
        arithmetic

     .  Comparing the result of a date expression to a literal date
        string

     .  REPLACEing a date field with a literal date string

     CTOD() is the inverse of DTOC() which converts a date value to a
     character string in the format specified by SET DATE and SET CENTURY.
     DTOS() also converts a date value to a character string in the form
     yyyymmdd.

 Examples

     .  This example uses CTOD() to initialize two date variables,
        using one as a GET and the other for RANGE validation:

        SET CENTURY ON
        dBegin := CTOD("01-26-1876")
        dCurrent := CTOD("")
        @ 10, 10 SAY "Enter date:" GET dCurrent ;
              RANGE dBegin, DATE()
        READ

     .  This example uses CTOD() to create a date value within a FOR
        condition:

        USE Inventory NEW
        REPLACE ALL Inventory->Price WITH ;
           Inventory->Price * 1.1 FOR ;
           Inventory->InvDate < CTOD("10/10/90")

 Files   Library is CLIPPER.LIB.

See Also: DATE() DTOC() DTOS() SET CENTURY SET DATE

 

C5_COLORSELECT

 COLORSELECT()
 Activate attribute in current color settings
------------------------------------------------------------------------------
 Syntax

     COLORSELECT(<nColorIndex>) --> NIL

 Returns

     Always returns NIL.

 Arguments

     <nColorIndex> is a number corresponding to the ordinal positions in
     the current list of color attributes, as set by SETCOLOR().

 Description

     COLORSELECT() activates the specified color pair from the current list
     of color attributes (established by SETCOLOR()).  Manifest constants for
     <nColorIndex> are defined in Color.ch.

     Color.ch constants
     ------------------------------------------------------------------------
     Constant          Value
     ------------------------------------------------------------------------
     CLR_STANDARD      0
     CLR_ENHANCED      1
     CLR_BORDER        2
     CLR_BACKGROUND    3
     CLR_UNSELECTED    4
     ------------------------------------------------------------------------

     COLORSELECT() does not alter the current SET Color setting.

     This table describes the scope of the Clipper color settings affected
     by SETCOLOR():

     Color settings
     ------------------------------------------------------------------------
     Setting        Scope
     ------------------------------------------------------------------------
     Standard       All screen output commands and functions
     Enhanced       GETs and selection highlights
     Border         Screen border (not supported on EGA and VGA monitors)
     Background     Not supported
     Unselected     Unselected GETs
     ------------------------------------------------------------------------

 Examples

     .  This example demonstrates use of COLORSELECT() with the
        Color.ch manifest constants:

        USE Sales NEW
        ? SETCOLOR()                   // displays "W/B,N/B,W/N,W/N,W/N"
                                       // in white on blue

        COLORSELECT(CLR_ENHANCED)      // enhanced is active color pair
        ? "I'm black and blue"         // displayed in black on blue
        COLORSELECT(CLR_STANDARD)      // restore standard color

 Files   Library is CLIPPER.LIB, header file is Color.ch.

See Also: SETCOLOR() SET COLOR*



C5_COL

 COL()
 Return the screen cursor column position
------------------------------------------------------------------------------
 Syntax

     COL() --> nCol

 Returns

     COL() returns an integer numeric value.  The range of the return value
     is zero to MAXCOL().

 Description

     COL() is a screen function that returns the current column position of
     the cursor.  The value of COL() changes whenever the cursor position
     changes on the screen.  Both console and full-screen commands can change
     the cursor position.  In addition, COL() is automatically set to zero
     whenever a CLEAR, CLEAR SCREEN, or CLS command is executed.

     Use COL() to position the cursor to a column relative to the current
     column.  It is generally used in combination with ROW() and all
     variations of the @ command.  In particular, use COL() and ROW() to
     create screen position-independent procedures or functions that pass the
     upper-left row and column as parameters.

     If DEVICE is SET TO PRINTER, all the output of @...SAY commands is
     directed to the printer and PROW() and PCOL() are updated instead of
     ROW() and COL().  Use these functions when you need to determine the
     position of the printhead.

 Examples

     .  This example displays a Customer name beginning at column 10.
        The customer's account status is then displayed to the right of the
        last character of the customer name using COL():

     USE Sales NEW

        CLS
        @ 1, 10 SAY "Customer Name: " + TRIM(Customer)
        @ ROW(), COL() + 1 SAY "Account status: " + Status

 Files   Library is CLIPPER.LIB.

See Also: @…CLEAR @…GET @…SAY CLEAR MAXCOL() PCOL()



C5_CMONTH

 CMONTH()
 Convert a date to a character month name
------------------------------------------------------------------------------
 Syntax

     CMONTH(<dDate>) --> cMonth

 Arguments

     <dDate> is the date value to convert.

 Returns

     CMONTH() returns the name of the month as a character string from a date
     value with the first letter uppercase and the rest of the string
     lowercase.  For a null date value, CMONTH() returns a null string ("").

 Description

     CMONTH() is a date conversion function useful for creating formatted
     date strings that can be used in reports, labels, or screens.

 Examples

     .  These examples illustrate CMONTH():

        ? CMONTH(DATE())                     // Result: September
        ? CMONTH(DATE() + 45)                // Result: October
        ? CMONTH(CTOD("12/01/94"))           // Result: December
        ? SUBSTR(CMONTH(DATE()), 1, 3) +;
           STR(DAY(DATE()))                  // Result: Sep 1

 Files   Library is CLIPPER.LIB.

See Also: CDOW() DATE() DAY() MONTH() YEAR()

 

C5_CHR

 CHR()
 Convert an ASCII code to a character value
------------------------------------------------------------------------------
 Syntax

     CHR(<nCode>) --> cChar

 Arguments

     <nCode> is an ASCII code in the range of zero to 255.

 Returns

     CHR() returns a single character value whose ASCII code is specified by
     <nCode>.

 Description

     CHR() is a numeric conversion function that converts an ASCII code to a
     character.  It is the inverse of ASC().  CHR() serves a number of common
     tasks including:

     .  Sending control codes and graphics characters to the screen or
        printer

     .  Ringing the bell

     .  Converting INKEY() return values to characters

     .  Stuffing the keyboard buffer

 Notes

     .  The null character: CHR(0) has a length of one (1) and is
        treated like any other character.  This lets you send it to any
        device or file, including a database file.

 Examples

     .  These examples illustrate CHR() with various arguments:

        ? CHR(72)                    // Result: H
        ? CHR(ASC("A") + 32)         // Result: a
        ? CHR(7)                     // Result: bell sounds

     .  These lines of code show the difference between a null string
        and the null character:

        ? LEN("")                   // Result: 0
        ? LEN(CHR(0))               // Result: 1

 Files   Library is CLIPPER.LIB.

See Also: ASC() INKEY()



C5_CDOW

 CDOW()
 Convert a date value to a character day of the week
------------------------------------------------------------------------------
 Syntax

     CDOW(<dExp>) --> cDayName

 Arguments

     <dExp> is the date value to convert.

 Returns

     CDOW() returns the name of the day of the week as a character string.
     The first letter is uppercase and the rest of the string is lowercase.
     For a null date value, CDOW() returns a null string ("").

 Description

     CDOW() is a date conversion function used in formatting date displays
     for reports, labels, and screens.

 Examples

     .  These examples illustrate CDOW():

        ? DATE()                      // Result: 09/01/90
        ? CDOW(DATE())                // Result: Friday
        ? CDOW(DATE() + 7)            // Result: Friday
        ? CDOW(CTOD("06/12/90"))      // Result: Tuesday

 Files   Library is CLIPPER.LIB.

See Also: CTOD() DATE() DAY() DOW()

 

C5_BROWSE

 BROWSE()*
 Browse records within a window
------------------------------------------------------------------------------
 Syntax

     BROWSE([<nTop>], [<nLeft>],
        [<nBottom>], [<nRight>]) lSuccess

 Arguments

     <nTop>, <nLeft>, <nBottom>, and <nRight> define the
     window coordinates.  If not specified, the default window coordinates
     are 1, 0 to MAXROW(), and MAXCOL().

 Returns

     BROWSE() returns false (.F.) if there is no database file in use;
     otherwise, it returns true (.T.).

 Description

     BROWSE() is a user interface function that invokes a general purpose
     table-oriented browser and editor for records in the current work area.
     For a list of the navigation keys which are used by BROWSE(), refer to
     the DBEDIT() function.  Note that Browse() is a compatibility function.
     DBEDIT() should be used in its place.  For a more complicated BROWSE(),
     TBROWSE() should be used.

 Notes

     .  Status line: BROWSE() supports a status line in the upper
        right corner of the browse window indicating one of the following:

        BROWSE() Status Line Messages
        ---------------------------------------------------------------------
        Message   Meaning
        ---------------------------------------------------------------------
        <new>     Append mode
        <bof>     Top of file
        <delete>  Current record is deleted
        Record    Record number display
        ---------------------------------------------------------------------

     .  BROWSE() has the following three modes:

        -  Browsing: This is the default mode of BROWSE().  Pressing any
           DBEDIT() navigation key moves the highlight to a new column or
           row.

        -  Field edit: Pressing Return on any field enters field edit
           using a GET.  Pressing Return terminates the edit mode, saving the
           changes.  Esc terminates without saving changes.  Since the field
           edit mode uses GET, all navigation and editing keys are READ keys.

        -  Append: GOing BOTTOM with Ctrl+PgDn and then pressing Down
           arrow enters append mode with the indicating message "<new>" on
           the status line.  A new blank record is then inserted.  Pressing
           Up arrow terminates the append mode, saving the new record if data
           has been entered.  If no data has been entered, the new record is
           not saved.

 Examples

     .  This is an example of browsing a file:

        USE File1 NEW
        BROWSE()

 Files   Library is EXTEND.LIB, source file is SOURCE\SAMPLE\BROWSE.PRG

See Also: DBEDIT()

 

C5_BREAK

 BREAK()
 Branch out of a BEGIN SEQUENCE...END construct
------------------------------------------------------------------------------
 Syntax

     BREAK(<exp>) --> NIL

 Arguments

     <exp> is the value passed to the RECOVER clause, if any.  Note that
     <exp> is not optional.  NIL may be specified if there is no break value.

 Returns

     BREAK() always returns NIL.

 Description

     The BREAK() function is identical in functionality to the BREAK
     statement.  The function must be executed during a SEQUENCE.  BREAK()
     has the advantage that, as an expression, it can be executed from a code
     block.

 Examples

     .  This example illustrates exiting a SEQUENCE from a code block:

        bSave := ERRORBLOCK( {|x| BREAK(x)} )

        BEGIN SEQUENCE
           .
           .
           .
        RECOVER USING objError
           .
           .
           .
        END

        ERRORBLOCK(bSave)

 Files   Library is CLIPPER.LIB.

See Also: BEGIN SEQUENCE


			

C5_BOF

 BOF()
 Determine when beginning of file is encountered
------------------------------------------------------------------------------
 Syntax

     BOF() --> lBoundary

 Returns

     BOF() returns true (.T.) after an attempt to SKIP backward beyond the
     first logical record in a database file; otherwise, it returns false
     (.F.).  If there is no database file open in the current work area,
     BOF() returns false (.F.).  If the current database file contains no
     records, BOF() returns true (.T.).

 Description

     BOF() is a database function used to test for a boundary condition when
     you are moving the record pointer backward through a database file using
     the SKIP command.  A simple usage example is a descending order record
     list with an ascending order index file.  A more sophisticated example
     is a screen paging routine that pages forward or backward through the
     current database file based on the key the user presses.  When the user
     attempts to page backward, you would use BOF() to test for a beginning
     of file condition before using the SKIP command to move the record
     pointer and repaint the screen.

     Once BOF() is set to true (.T.), it retains its value until there is
     another attempt to move the record pointer.

     By default, BOF() operates on the currently selected work area.  It can
     be made to operate on an unselected work area by specifying it within an
     aliased expression (see example below).

     The SKIP command is the only record movement command that can set BOF()
     to true (.T.).

 Examples

     .  This example demonstrates BOF() by attempting to move the
        record pointer before the first record:

        USE Sales NEW
        ? RECNO(), BOF()               // Result: 1 .F.
        SKIP -1
        ? RECNO(), BOF()               // Result: 1 .T.

     .  This example uses aliased expressions to query the value of
        BOF() in unselected work areas:

        USE Sales NEW
        USE Customer NEW
        USE Invoices NEW

        ? Sales->(BOF()), Customer->(BOF())

 Files   Library is CLIPPER.LIB.

See Also: EOF() SKIP