E&l1O(10U(sp16.6h8.5vsbT&k7.2H&l5.2cL&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CALERT()
Display a simple modal dialog box

Syntax
    ALERT( <cMessage> [, <aOptions] ) --> <nChoice>

Arguments
    <cMessage> defines a message shown centered in the alert box.
    If the message contains one or more semicolons, the text after the
    semicolons is centered on succeeding lines in the dialog box.

    <aOptions> defines a list of possible responses to the dialog
    box.

Returns
    ALERT() returns a numeric value indicating which option was
    chosen.  If the Esc key is pressed, the value returned is zero.

Description

    The ALERT() function creates a simple modal dialog.  It is useful in
    error handlers and other "pause" functions.  The user can respond
    chosen by moving a highlight bar and pressing the Return or Space
    keys, or by pressing the key corresponding to the first letter of
    the option.  If <aOptions> is not supplied, a single "Ok" option is
    presented.

    ALERT() is sensitive to the presence or absence of the Clipper
    full-screen I/O system.  If the full-screen system is not present,
    ALERT() uses standard I/O to display the message and options
    tty-style.

Examples

    This examples demonstrates how an alert dialog box is used.  First,
    the array of options is defined, the ALERT() function is then
    called to get the user's selection, and finally the user's choice
    is handled with a DO CASE...ENDCASE control structure.

    #define AL_SAVE   1
    #define AL_CANCEL 2
    #define AL_CONT   3

    // Define an array of options
    aOptions := {"Save", "Don't Save", "Continue"}

    // Display the dialog box and get the user's selection
    nChoice  := ALERT("File has changed...", aOptions)
    // Handle the user's request
    DO CASE
    CASE nChoice == AL_SAVE
       ? "Save"
    CASE nChoice == AL_CANCEL
       ? "Don't Save"
    CASE nChoice == AL_CONT
       ? "Continue"
    OTHERWISE
       ? "Escape"
    ENDCASE
    //
    RETURN

Files:  Library is CLIPPER.LIB
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CALLTRIM()
Remove leading and trailing spaces from a character string

Syntax

    ALLTRIM(<cString>) --> cTrimString

Arguments

    <cString> is the character expression to trim.

Returns

    ALLTRIM() returns a character string with leading and trailing spaces
    removed.

Description

    ALLTRIM() is a character function that removes both leading and
    trailing spaces from a string.  It is related to LTRIM() and RTRIM()
    which remove leading and trailing spaces, respectively.  The inverse of
    ALLTRIM(), LTRIM(), and RTRIM() are the PADC(), PADR(), and PADL()
    functions which center, right-justify, or left-justify character
    strings by padding them with fill characters.

Examples

    The following example creates a string with both leading and trailing
    spaces, and then trims them with ALLTRIM():

    cString = SPACE(10) + "string" + SPACE(10)
    ? LEN(cString)                      // Result: 26
    ? LEN(ALLTRIM(cString))             // Result: 6

Files:  Library is EXTEND.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CATAIL()
Return the highest numbered element of an array

Syntax

    ATAIL(<aArray>) --> element

Arguments

    <aArray> is the array.

Returns

    ATAIL() returns a value or a reference to an array or object.  The
    array is not changed.

Description

    ATAIL() is an array function that returns the highest numbered
    element of an array.  It can be used in applications as shorthand
    for <aArray>[LEN(<aArray>)] when you need to obtain the last
    element of an array.

Examples

    The following example creates a literal array and returns that last
    element of the array:

    aArray := {"a", "b", "c", "d"}
    ? ATAIL(aArray)                       // Result: d

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBAPPEND()
Add a new record

Syntax

    DBAPPEND() --> NIL

Returns

    DBAPPEND() always returns NIL.

Description

    DBAPPEND() adds a new record to the database (.dbf) file associated
    with the current work area.  If successfully added, each field in the
    record is set to the empty value for its data type and the new record
    becomes the current record.

    DBAPPEND() performs the same function as the standard APPEND BLANK
    command.  For more information, refer to the APPEND BLANK command.

Notes

       Logical records: DBAPPEND() does not respect logical
       visibility.  That is, if the record is successfully added, it
       becomes the current record regardless of any index or filter
       condition.

       Network environment: For a shared database on a network,
       DBAPPEND() automatically places a record lock on the new record.
       If the record cannot be locked, it is not added and a recoverable
       runtime error occurs.  The default Clipper error handler handles
       this error by setting the system NETERR() status to true (.T.) and
       continuing execution.  For more information, refer to the Network
       Programming chapter of the Programming and Utilities Guide.

Examples

    Employee->( DBAPPEND() )

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCLEARFILTER()
Clear a filter condition

Syntax

    DBCLEARFILTER() --> NIL

Returns

    DBCLEARFILTER() always returns NIL.

Description

    DBCLEARFILTER() clears the logical filter condition, if any, for the
    current work area.

    DBCLEARFILTER() performs the same function as the standard SET FILTER
    command with no expression specified.  For more information, refer to
    the SET FILTER command.

Notes

       Logical records: DBCLEARFILTER() affects which records
       are logically visible in the current work area.  For more
       information, refer to DBSETFILTER() and the SET FILTER command.

Examples

    DBCLEARFILTER()

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCLEARINDEX()
Close all indexes for the current work area

Syntax

    DBCLEARINDEX() --> NIL

Returns

    DBCLEARINDEX() always returns NIL.

Description

    DBCLEARINDEX() closes any active indexes for the current work area.
    Any pending index updates are written and the index files are closed.

    DBCLEARINDEX() performs the same function as the standard SET INDEX
    command with no indexes specified.  For more information, refer to the
    SET INDEX command.

Examples

    DBCLEARINDEX()

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCLEARRELATION()
 Clear active relations

Syntax

    DBCLEARRELATION() --> NIL

Returns

    DBCLEARRELATION() always returns NIL.

Description

    DBCLEARRELATION() clears any active relations for the current work
    area.

    DBCLEARRELATION() performs the same function as the standard SET
    RELATION TO command with no clauses specified.  For more information,
    refer to the SET RELATION command.

Examples

    DBCLEARRELATION()

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCLOSEALL()
Close all occupied work areas

Syntax

    DBCLOSEALL() --> NIL

Returns
    DBCLOSEALL() always returns NIL.

Description

    DBCLOSEALL() releases all occupied work areas from use.  It is
    equivalent to calling DBCLOSEAREA() on every occupied work area.
    DBCLOSEAREA() has the same effect as the standard CLOSE DATABASES
    command.  For more information, refer to the USE and CLOSE commands.

Examples

    DBCLOSEALL()

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCLOSEAREA()
Close a work area

Syntax

   DBCLOSEAREA() --> NIL

Returns

    DBCLOSEAREA() always returns NIL.

Description

    DBCLOSEAREA() releases the current work area from use.  Pending
    updates are written, pending locks are released, and any resources
    associated with the work area are closed or released.  DBCLOSEAREA()
    is equivalent to the standard CLOSE command or the USE command with no
    clauses.  For more information, refer to the USE and CLOSE commands.

Examples
    Employees->( DBCLOSEAREA() )

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCOMMIT()
Flush pending updates

Syntax

    DBCOMMIT() --> NIL

Returns

    DBCOMMIT() always returns NIL.

Description

    DBCOMMIT() causes all updates to the current work area to be written
    to disk.  All updated database and index buffers are written to DOS
    and a DOS COMMIT request is issued for the database (.dbf) file and
    any index files associated with the work area.

    DBCOMMIT() performs the same function as the standard COMMIT command
    except that it operates only on the current work area.  For more
    information, refer to the COMMIT command.

Notes

       Network environment: DBCOMMIT() causes updates to the
       database to become visible to other processes.  For more
       information, refer to the Network Programming chapter in the
       Programming and Utilities Guide.

Examples

    DBCOMMIT()

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCOMMITALL()
Flush pending updates in all work areas

Syntax

    DBCOMMITALL() --> NIL

Returns

    DBCOMMITALL() always returns NIL.

Description

    DBCOMMITALL() causes all pending updates to all work areas to be
    written to disk.  It is equivalent to calling DBCOMMIT() for every
    occupied work area.

    For more information, refer to DBCOMMIT() and the COMMIT command.

Examples
    DBCOMMITALL()

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCREATE()
Create a database file from a database structure array

Syntax

    DBCREATE(<cDatabase>, <aStruct>) --> NIL

Arguments

    <cDatabase> is the name of the new database file, with an optional
    drive and directory, specified as a character string.  If specified
    without an extension (.dbf) is assumed.

    <aStruct> is an array that contains the structure of <cDatabase> as
    a series of subarrays, one per field.  Each subarray contains the
    definition of each field's attributes and has the following
    structure:

    Table 5-7: Field Definition Subarray
    =================================================================
    Position           Metasymbol        Dbstruct.ch
    =================================================================
    1                  cName             DBS_NAME
    2                  cType             DBS_TYPE
    3                  nLength           DBS_LEN
    4                  nDecimals         DBS_DEC
    =================================================================

Returns

    DBCREATE() always returns NIL.

Description

    DBCREATE() is a database function that creates a database file from an
    array containing the structure of the file.  The array may be created
    programmatically or using DBSTRUCT().  DBCREATE() is similar to the
    CREATE FROM command which creates a new database file structure from a
    structure extended file.  A structure extended file is created either
    by the CREATE or COPY STRUCTURE EXTENDED commands.

    Before using DBCREATE(), you must first create the <aStruct> array and
    fill it with the field definition arrays according to the structure
    stated above.  When creating a field definition array, there are some
    specific rules including:

       All field attributes must be specified with a value of the proper
       data type for the attribute.  The decimals attribute must be
       specified--even for non-numeric fields.  If the field does not
       have a decimals attribute, specify zero.

       The type attribute must be specified using the first letter of the
       data type as a minimum.  Longer and more descriptive terms can be
       used for readability.  For example, both "C" and "Character" can be
       specified as the type attribute for character fields.

       In Clipper, character fields can have a length of up to 64,000
       characters.  Unlike the CREATE FROM command, DBCREATE() does not use
       the decimals attribute to specify the high order part of the field
       length.  The field length is specified directly, regardless of its
       magnitude.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C    To make references to the various elements of the field definition
    subarray more readable, the header file called Dbstruct.ch is supplied
    which contains the #defines to assign a name to the array position for
    each field attribute.  It is located in \CLIPPER5\INCLUDE.

Examples

       The following example creates an empty array and then adds field
       definition subarrays using the AADD() function before creating
       People.dbf.  You might use this technique if you are adding field
       definitions to your structure array dynamically:

       aDbf := {}
       AADD(aDbf, { "Name", "C", 25, 0 })
       AADD(aDbf, { "Address", "C", 1024, 0 })
       AADD(aDbf, { "Phone", "N", 13, 0 })
       //
       DBCREATE("People", aDbf)

       This example performs the same types of actions but declares the
       structure array as a two-dimensional array, and then uses subscript
       addressing to specify the field definitions:

       #include "Dbstruct.ch"
       //
       LOCAL aDbf[1][4]
       aDbf[1][ DBS_NAME ] := "Name"
       aDbf[1][ DBS_TYPE ] := "Character"
       aDbf[1][ DBS_LEN ]  := 25
       aDbf[1][ DBS_DEC ]  := 0
       //
       DBCREATE("Name", aDbf)

Files:  Library is CLIPPER.LIB, header file is Dbstruct.ch.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBCREATEINDEX()
Create an index file

Syntax

    DBCREATEINDEX(<cIndexName>, <cKeyExpr>,
       [<bKeyExpr>], [<lUnique>]) --> NIL

Arguments

    <cIndexName> is a character value that specifies the filename of
    the index file to be created.

    <cKeyExpr> is a character value that expresses the index key
    expression in textual form.

    <bKeyExpr> is an optional code block that expresses the index key
    expression in executable form.

    <lUnique> is an optional logical value that specifies whether a
    unique index is to be created.  If <lUnique> is omitted, the current
    global _SET_UNIQUE setting is used.

Returns

    DBCREATEINDEX() always returns NIL.

Description

    DBCREATEINDEX() creates an index for the database (.dbf) file
    associated with the current work area.  If the work area has active
    indexes, they are closed.  After the new index is created, it becomes
    the controlling index for the work area and the work area is
    positioned to the first logical record.

    DBCREATEINDEX() performs the same function as the standard INDEX
    command.  For more information, refer to the INDEX command.

Notes
       Side effects: DBCREATEINDEX() is guaranteed to create an
       index that, when made active, will impose the specified logical
       order on the database.  The key expression is not necessarily
       evaluated at any particular time, by any particular means, or on
       any particular record or series of records.  If the key expression
       relies on information external to the database file or work area,
       the effect is unpredictable.  If the key expression changes the
       state of the work area (e.g., by moving to a different record or
       changing the contents of a record), the effect is unpredictable.

       Evaluation context: When the key expression is
       evaluated, the associated work area is automatically selected as
       the current work area before the evaluation; the previously
       selected work area is automatically restored afterward.

       Network environment: DBCREATEINDEX() creates the new
       index for the exclusive use of the current process.

Examples

    USE Employees NEW
    DBCREATEINDEX( "Name",, "Name" )

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBDELETE()
Mark a record for deletion

Syntax

    DBDELETE() --> NIL

Returns

    DBDELETE() always returns NIL.

Description

    DBDELETE() marks the current record as deleted.  Records marked for
    deletion can be filtered using SET DELETED or removed from the file
    using the PACK command.

    DBDELETE() performs the same function as the standard DELETE command
    with a scope of the current record.  For more information, refer to
    the DELETE command.

Notes
       Logical records: If the global _SET_DELETED status is
       true (.T.), deleted records are not logically visible.  That is,
       database operations which operate on logical records will not
       consider records marked for deletion.  Note, however, that if
       _SET_DELETED is true (.T.) when the current record is marked for
       deletion, the record remains visible until it is no longer the
       current record.

       Network environment: For a shared database on a network,
       DBDELETE() requires the current record to be locked.  For more
       information, refer to the Network Programming chapter of the
       Programming and Utilities Guide.

Examples

    DBDELETE()

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBGOBOTTOM()
Move to the last logical record

Syntax

    DBGOBOTTOM() --> NIL

Returns

    DBGOBOTTOM() always returns NIL.

Description

    DBGOBOTTOM() moves to last logical record in the current work area.

    DBGOBOTTOM() performs the same function as the standard GO BOTTOM
    command.  For more information, refer to the GO command.

Notes
       Logical records: DBGOBOTTOM() operates on logical
       records.  If there is an active index, DBGOBOTTOM() moves to the
       last record in indexed order.  If a filter is set, only records
       which meet the filter condition are considered.

       Controlling order: If the work area has more than one
       active index, the operation is performed using the controlling
       order as set by DBSETORDER() or the SET ORDER command.  For more
       information, refer to the SET ORDER command.

       Network environment: For a shared file on a network,
       moving to a different record may cause updates to the current
       record to become visible to other processes.  For more information,
       refer to the Network Programming chapter in the Programming and
       Utilities Guide.

Examples

    DBGOBOTTOM()

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBGOTO()
Move to the record having the specified record number

Syntax

   DBGOTO(<nRecordNumber>) --> NIL

Arguments

    <nRecordNumber> is a numeric value that specifies the record
    number of the desired record.

Returns

    DBGOTO() always returns NIL.

Description

    DBGOTO() moves to the record whose record number is equal to
    <nRecordNumber>.  If no such record exists, the work area is
    positioned to LASTREC() + 1 and both EOF() and BOF() return true (.T.)

    DBGOTO() performs the same function as the standard GO command.  For
    more information, refer to the GO command.

Notes
       Logical records: DBGOTO() does not respect logical
       visibility.  That is, if the specified record exists, it will
       become the current record regardless of any index or filter
       condition.

       Network environment: For a shared file on a network,
       moving to a different record may cause updates to the current
       record to become visible to other processes.  For more information,
       refer to the Network Programming chapter in the Programming and
       Utilities Guide.

Examples

    DBGOTO(5)

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBGOTOP()
Move to the first logical record

Syntax

    DBGOTOP() --> NIL

Returns

    DBGOTOP() always returns NIL.

Description

    DBGOTOP() moves to the first logical record in the current work area.

    DBGOTOP() performs the same function as the standard GO TOP command.
    For more information, refer to the GO TOP command.

Notes
       Logical records: DBGOTOP() operates on logical records.
       If there is an active index, DBGOTOP() moves to the first record in
       indexed order.  If a filter is set, only records which meet the
       filter condition are considered.

       Controlling order: If the work area has more than one
       active index, the operation is performed using the controlling
       order as set by DBSETORDER() or the SET ORDER command.  For more
       information, refer to the SET ORDER command.

       Network environment: For a shared file on a network,
       moving to a different record may cause updates to the current
       record to become visible to other processes.  For more information,
       refer to the Network Programming chapter in the Programming and
       Utilities Guide.

Examples

    DBGOTOP()
    WHILE ( !EOF() )
       ? FIELD->Name
       DBSKIP()
    END

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBRECALL()
Reinstate a record marked for deletion

Syntax

    DBRECALL() --> NIL

Returns

    DBRECALL() always returns NIL.

Description

    DBRECALL() causes the current record to be reinstated if it is marked
    for deletion.

    DBRECALL() performs the same function as the standard RECALL command.
    For more information, refer to the DELETE and RECALL commands.

Notes

       Logical records: Reinstating a deleted record affects
       the record's logical visibility if the global _SET_DELETED status
       is true (.T.)  For more information, refer to the DBDELETE()
       function and the DELETE and RECALL commands.

       Network environment: For a shared database on a network,
       DBRECALL() requires the current record to be locked.  For more
       information, refer to the Network Programming chapter of the
       Programming and Utilities Guide.

Examples

    DBRECALL()

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBREINDEX()
Recreate all active indexes for the current work area

Syntax

    DBREINDEX() --> NIL

Returns

    DBREINDEX() always returns NIL.

Description

    DBREINDEX() rebuilds all active indexes associated with the current
    work area.  After the indexes are recreated, the work area is moved to
    the first logical record in the controlling order.

    DBCREATEINDEX() performs the same function as the standard REINDEX
    command.  For more information, refer to the REINDEX command.

Examples

    DBREINDEX()

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBRELATION()
Return the linking expression of a specified relation

Syntax

    DBRELATION(<nRelation>) --> cLinkExp

Arguments

    <nRelation> is the position of the desired relation in the list of
    current work area relations.  The relations are numbered according to
    the order in which they were defined with SET RELATION.

Returns

    DBRELATION() returns a character string containing the linking
    expression of the relation specified by <nRelation>.  If there is no
    RELATION SET for <nRelation>, DBRELATION() returns a null string ("").

Description

    DBRELATION() is a database function that is used in combination with
    DBRSELECT() to determine the linking expression and work area of an
    existing relation created with the SET RELATION command.

    DBRELATION() returns the linking expression defined by the TO clause.
    DBRSELECT() returns the work area linked as defined by the INTO clause.

    By default, DBRELATION() 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).

Notes

       Declared variables: A character string returned by DBRELATION()
       may not operate correctly when re-compiled and executed using the
       macro (&) operator if the original expression contained references
       to local or static variables, or otherwise depends on compile-time
       declarations.

Examples

       This example opens three database files, sets two child relations
       from the parent work area, and then displays the linking expression
       to the second child work area:

       USE Invoices INDEX Invoices NEW
       USE BackOrder INDEX BackOrder NEW
       USE Customer INDEX Customer NEW
       SET RELATION TO CustNum INTO Invoices, OrderNum INTO BackOrder
       //
       ? DBRELATION(2)                     // Result: OrderNum

       Later you can query the same linking expression from an unselected
       work area by using an aliased expression like this:

       USE Archive NEW
       ? Customer->(DBRELATION(2))         // Result: OrderNum

       This example is a user-defined function, Relation(), that returns
       the results of both DBRELATION() and DBRSELECT() as an array:

       FUNCTION Relation( nRelation )
          RETURN { DBRELATION(nRelation), ALIAS(DBRSELECT(nRelation)) }

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBSEEK()
Move to the record having the specified key value

Syntax

    DBSEEK(<expKey>, [<lSoftSeek>]) --> lFound

Arguments

    <expKey> is a value of any type that specifies the key value
    associated with the desired record.

    <lSoftSeek> is an optional logical value that specifies whether a
    soft seek is to be performed.  This determines how the work area is
    positioned if the specified key value is not found (see below).  If
    <lSoftSeek> is omitted, the current global _SET_SOFTSEEK setting is
    used.

Returns

    DBSEEK() returns true (.T.) if the specified key value was found;
    otherwise, it returns false (.F.)

Description

    DBSEEK() moves to the first logical record whose key value is equal to
    <expKey>.  If such a record is found, it becomes the current record
    and DBSEEK() returns true (.T.)  Otherwise, DBSEEK() returns false
    (.F.) and the positioning of the work area is as follows: for a normal
    (not soft) seek, the work area is positioned to LASTREC() + 1 and
    EOF() returns true (.T.); for a soft seek, the work area is positioned
    to the first record whose key value is greater than the specified key
    value.  If no such record exists, the work area is positioned to
    LASTREC() + 1 and EOF() returns true (.T.)

    For a work area with no active indexes, DBSEEK() has no effect.

    DBSEEK() performs the same function as the standard SEEK command.  For
    more information, refer to the SEEK command.

Notes
       Logical records: DBSEEK() operates on logical records.
       Records are considered in indexed order.  If a filter is set, only
       records which meet the filter condition are considered.

       Controlling order: If the work area has more than one
       active index, the operation is performed using the controlling
       order as set by DBSETORDER() or the SET ORDER command.  For more
       information, refer to the SET ORDER command.
       Network environment: For a shared file on a network,
       moving to a different record may cause updates to the current
       record to become visible to other processes.  For more information,
       refer to the Network Programming chapter in the Programming and
       Utilities Guide.

Examples
    ACCEPT "Employee name: " TO cName
    IF ( Employee->(DBSEEK(name)) )
       Employee->(ViewRecord())
    ELSE
       ? "Not found"
    END

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBSELECTAREA()
Change the current work area

Syntax

    DBSELECTAREA(<nArea> | <cAlias>) --> NIL

Arguments

    <nArea> is a numeric value between zero and 250, inclusive, that
    specifies the work area to be selected.

    <cAlias> is a character value that specifies the alias of a
    currently occupied work area to be selected.

Returns

    DBSELECTAREA() always returns NIL.

Description

    DBSELECTAREA() causes the specified work area to become the current
    work area.  All subsequent database operations will apply to this work
    area unless another work area is explicitly specified for an
    operation.  DBSELECTAREA() performs the same function as the standard
    SELECT command.  For more information, refer to the SELECT command.

Notes

       Selecting zero: Selecting work area zero causes the
       lowest numbered unoccupied work area to become the current work
       area.

       Alias expressions: The alias operator can be used to
       temporarily select a work area while an expression is evaluated and
       automatically restore the previously selected work area afterward.
       For more information, refer to the alias operator.

Examples

    DBSELECTAREA("Table1")

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBSETDRIVER()
Return the default database driver and optionally set a new driver.

Syntax

    DBSETDRIVER([<cDriver>]) --> cCurrentDriver

Arguments

    <cDriver> is an optional character value that specifies the name
    of the database driver that should be used to activate and manage new
    work areas when no driver is explicitly specified.

Returns

    DBSETDRIVER() returns the name of the current default driver.

Description

    DBSETDRIVER() sets the database driver to be used when activating new
    work areas without specifying a driver.  If the specified driver is
    not available to the application, the call has no effect.
    DBSETDRIVER() returns the name of the current default driver, if any.

Examples

    This example makes the "DBFNDX" driver the default driver.  If the
    driver is not available, a message is issued:

    DBSETDRIVER("DBFNTX")

    IF ( DBSETDRIVER() <> "DBFNTX" )
       ? "DBFNTX driver not available"
    ENDIF

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBSETFILTER()
Set a filter condition

Syntax

    DBSETFILTER(<bCondition>, [<cCondition>]) --> NIL

Arguments

    <bCondition> is a code block that expresses the filter condition
    in executable form.

    <cCondition> is an optional character value that expresses the
    filter condition in textual form.  If <cCondition> is omitted, the
    DBFILTER() function will return an empty string for the work area.

Returns

    DBSETFILTER() always returns NIL.

Description

    DBSETFILTER() sets a logical filter condition for the current work
    area.  When a filter is set, records which do not meet the filter
    condition are not logically visible.  That is, database operations
    which act on logical records will not consider these records.

    The filter expression supplied to DBSETFILTER() should evaluate to
    true (.T.) if the current record meets the filter condition;
    otherwise, it should evaluate to false (.F.)

    The filter expression may be supplied either as a code block
    (<bCondition>) or as both a code block and equivalent text
    (<cCondition>).  If both versions are supplied, they must express the
    same condition.  If the text version is not supplied, DBFILTER() will
    return an empty string for the work area.

    DBSETFILTER() performs the same function as the standard SET FILTER
    command.  For more information, refer to the SET FILTER command.

Notes

       Logical records: DBSETFILTER() affects which records are
       logically visible (see above).

       Side effects: Setting a filter condition is only
       guaranteed to restrict visibility of certain records as described
       above.  The filter expression is not necessarily evaluated at any
       particular time, by any particular means, or on any particular
       record or series of records.  If the filter expression relies on
       information external to the database file or work area, the effect
       is unpredictable.  If the filter expression changes the state of
       the work area (e.g., by moving to a different record or changing
       the contents of a record), the effect is unpredictable.

       Evaluation context: When the filter expression is
       evaluated, the associated work area is automatically selected as
       the current work area before the evaluation; the previously
       selected work area is automatically restored afterward.

Examples

    USE Employee NEW
    DBSETFILTER( {|| Age < 40}, "Age < 40" )

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBSETINDEX()
Open an index

Syntax

    DBSETINDEX(<cIndexName>) --> NIL

Arguments

    <cIndexName> is a character value that specifies the filename of
    the index file to be opened.

Returns

    DBSETINDEX() always returns NIL.

Description

    DBSETINDEX() opens an index file for the current work area.  Any index
    files already associated with the work area continue to be active.  If
    the newly opened index is the only index associated with the work
    area, it becomes the controlling index; otherwise, the controlling
    order remains unchanged.

    After the new index file is opened, the work area is positioned to the
    first logical record in the controlling order.

    DBSETINDEX() performs the same function as the standard SET INDEX
    command or the INDEX clause of the USE command.  For more information,
    refer to the SET INDEX command.

Notes

       Logical records: Activating an index affects the logical
       order of records in the work area.  That is, when an index is
       active, commands which operate on logical records will consider
       records in indexed order.  If the controlling index is a unique
       index, records with duplicate index keys will not be logically
       visible.

       Network environment: DBSETINDEX() opens the index for
       shared access if the associated database file was opened for shared
       access.  Otherwise, the index is opened for exclusive access.

Examples

    DBSETINDEX()

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBSETORDER()
Set the controlling order

Syntax

    DBSETORDER(<nOrderNum>) --> NIL

Arguments

    <nOrderNum> is a numeric value that specifies which of the active
    indexes is to be the controlling index.

Returns

    DBSETORDER() always returns NIL.

Description

    DBSETORDER() controls which of the current work area's active indexes
    is the controlling index.  The controlling index is the index which
    determines the logical order of records in the work area.

    Active indexes are numbered from 1 to the number of active indexes,
    based on the order in which the indexes were opened.  <nOrderNum>
    specifies the number of the desired index.

    DBSETORDER() performs the same function as the standard SET ORDER
    command.  For more information, refer to the SET ORDER command.

Notes

       Setting order to zero: Setting order to zero causes the
       work area to be accessed in natural (record number) order.  Only
       the logical order of the records is affected; any open indexes
       continue to be active and are properly maintained.

Examples

    USE Employee NEW
    SET INDEX TO Name, Age
    DBSETORDER(2)

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBSETRELATION()
Relate two work areas

Syntax

    DBSETRELATION(<nArea> | <cAlias>, <bExpr>, [<cExpr>]) --> NIL

Arguments

    <nArea> is a numeric value that specifies the work area number of
    the child work area.

    <cAlias> is a character value that specifies the alias of the
    child work area.

    <bExpr> is a code block that expresses the relational expression
    in executable form.

    <cExpr> is an optional character value that expresses the
    relational expression in textual form.  If <cExpr> is omitted, the
    DBRELATION() function will return an empty string for the relation.

Returns

    DBSETRELATION() always returns NIL.

Description

    DBSETRELATION() relates the work area specified by <nArea> or <cAlias>
    (the child work area), to the current work area (the parent work
    area).  Any existing relations remain active.

    Relating work areas causes the child work area to become synchronized
    with the parent work area.  This is achieved by automatically
    repositioning the child work area whenever the parent work area moves
    to a new record.  If the child work area has an active index, moving
    the parent work area causes an automatic SEEK operation in the child
    work area; the seek key is based on the expression specified by
    <bExpr> and/or <cExpr>.  If the child work area has no active index,
    moving the parent work area causes an automatic GOTO in the child work
    area; the record number for the GOTO is based on the expression
    specified by <bExpr> and/or <cExpr>.

    The relational expression may be supplied either as a code block
    (<bExpr>) or as both a code block and equivalent text (<cExpr>).   If
    both versions are supplied, they must be equivalent.  If the text
    version is not supplied, DBRELATION() will return an empty string for
    the relation.

    DBSETRELATION() performs the same function as the standard SET
    RELATION command with the ADDITIVE clause.  For more information,
    refer to the SET RELATION command.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CNotes

       Side effects: Relating work areas is only guaranteed to
       synchronize the work areas as described above.  The relational
       expression is not necessarily evaluated at any particular time, by
       any particular means, or on any particular record or series of
       records.  If the relational expression relies on information
       external to the parent work area or its associated database file,
       the effect is unpredictable.  If the expression changes the state
       of either work area (e.g., by moving to a different record or
       changing the contents of a record), the effect is unpredictable.

       Evaluation context: When the relational expression is
       evaluated, the parent work area is automatically selected as the
       current work area before the evaluation; the previously selected
       work area is automatically restored afterward.

       Soft seeking: Seek operations that occur as part of
       relational positioning are never soft seeks.  If a relational
       movement is unsuccessful, the child work area is positioned to
       LASTREC() + 1, its FOUND() status returns false (.F.), and its
       EOF() status returns true (.T.)

Examples

    USE Employee NEW
    USE Department NEW INDEX Dept

    SELECT Employee
    DBSETRELATION("Department", {|| Employee->Dept}, "Employee->Dept")
    LIST Employee->Name, Department->Name

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBSKIP()
Move relative to the current record

Syntax

    DBSKIP([<nRecords>]) --> NIL

Arguments

    <nRecords> is the number of logical records to move, relative to
    the current record.  A positive value means to skip forward, and a
    negative value means to skip backward.  If <nRecords> is omitted, a
    value of 1 is assumed.

Returns

    DBSKIP() always returns NIL.

Description

    DBSKIP() moves either forward or backward relative to the current
    record.  Attempting to skip forward beyond the last record positions
    the work area to LASTREC() + 1 and EOF() returns true (.T.)
    Attempting to skip backward beyond the first record positions the work
    area to the first record and BOF() returns true (.T.)

    DBSKIP() performs the same function as the standard SKIP command.  For
    more information, refer to the SKIP command.

Notes

       Logical records: DBSKIP() operates on logical records.
       If there is an active index, records are considered in indexed
       order.  If a filter is set, only records which meet the filter
       condition are considered.

       Controlling order: If the work area has more than one
       active index, the skip operation is performed using the controlling
       order as set by DBSETORDER() or the SET ORDER command.  For more
       information, refer to the SET ORDER command.

       Network environment: For a shared file on a network,
       moving to a different record may cause updates to the current
       record to become visible to other processes.  For more information,
       refer to the Network Programming chapter in the Programming and
       Utilities Guide.

Examples

    DBGOTOP()
    WHILE ( !EOF() )
       ? FIELD->Name
       DBSKIP()
    END

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBUNLOCK()
Release all locks for the current work area

Syntax

    DBUNLOCK() --> NIL

Returns

    DBUNLOCK() always returns NIL.

Description

    DBUNLOCK() releases any record or file locks obtained by the current
    process for the current work area.  DBUNLOCK() is only meaningful on a
    shared database in a network environment.

    DBUNLOCK() performs the same function as the standard UNLOCK command.
    For more information, refer to the UNLOCK command.

Notes

       Network environment: Releasing locks may cause updates
       to the database to become visible to other processes.  For more
       information, refer to the Network Programming chapter in the
       Programming and Utilities Guide.

Examples

    DBUNLOCK()

Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBUNLOCKALL()
Release all locks for all work areas

Syntax

    DBUNLOCKALL() --> NIL

Returns

    DBUNLOCKALL() always returns NIL.

Description

    DBUNLOCKALL() releases any record or file locks obtained by the
    current process for any work area.  DBUNLOCKALL() is only meaningful
    on a shared database in a network environment.  It is equivalent to
    calling DBUNLOCK() on every occupied work area.

    DBUNLOCKALL() performs the same function as the UNLOCK ALL command.
    For more information, refer to the UNLOCK ALL command.

Examples

    DBUNLOCKALL()

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200CDBUSEAREA()
Use a database file in a work area

Syntax

    DBUSEAREA( [<lNewArea>], [<cDriver>], <cName>, [<cAlias>],
       [<lShared>], [<lReadonly>]) --> NIL

Arguments
    <lNewArea> is an optional logical value.  A value of true (.T.)
    specifies that the lowest numbered unoccupied work area should be
    selected as the current work area before the use operation.  If
    <lNewArea> is false (.F.) or omitted, the current work area is used;
    if the work area is occupied, it is closed first.

    <cDriver> is an optional character value.  If present, it
    specifies the name of the database driver which will be used to
    service the work area.  If <cDriver> is omitted, the current default
    driver is used (see note below).
    <cName> specifies the name of the database (.dbf) file to be
    opened.

    <cAlias> is an optional character value.  If present, it specifies
    the alias to be associated with the work area.  The alias must
    constitute a valid Clipper identifier.  If <cAlias> is omitted, a
    default alias is constructed from <cName>.

    <lShared> is an optional logical value.  If present, it specifies
    whether the database (.dbf) file should be accessible to other
    processes on a network.  A value of true (.T.) specifies that other
    processes should be allowed access; a value of false (.F.) specifies
    that the current process is to have exclusive access.  If <lShared> is
    omitted, the current global _SET_EXCLUSIVE setting determines whether
    shared access is allowed.

    <lReadonly> is an optional logical value that specifies whether
    updates to the work area are prohibited.  A value of true (.T.)
    specifies that updates are prohibited; a value of false (.F.)
    specifies that updates are allowed.  A value of true (.T.) also causes
    the specified database (.dbf) file to be opened for read-only access.
    If <lReadonly> is omitted, the default value is false (.F.)

Returns
    DBUSEAREA() always returns NIL.

Description
    DBUSEAREA() associates the specified database (.dbf) file with the
    current work area.

    DBUSEAREA() performs the same function as the standard USE command.
    For more information, refer to the USE command.

Notes
       Current driver: If no driver is specified in the call to
       DBUSEAREA() the default driver is used.  If more than one driver is
       available to the application, the default driver is the driver
       specified in the most recent call to DBSETDRIVER().  If
       DBSETDRIVER() has not been called, the default driver is
       unpredictable.

Examples
    DBUSEAREA(.T., "DBFNDX", "Employees")

Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  DEVOUT()
  Write a value to the current device

  Syntax

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

  Arguments

      <exp> is the value to display.

      <cColorString> is an optional argument that defines the display
      color of <exp>.  If the current DEVICE setting is SCREEN, the
      output is displayed in the specified color.

      If not specified, <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.  If you
      want to specify a literal color setting, it must be specified
      enclosed in quote marks.

  Returns

      DEVOUT() always returns NIL.

  Description

      DEVOUT() is a full-screen display function that writes the value of a
      single expression to the current device at the current cursor or
      printhead position.  DEVOUT() is used in combination with DEVPOS() in
      STD.CH to implement the @...SAY command.

  Examples

      The following example shows the relationship between the  DEVOUT()
      function and the @...SAY command:

      DEVPOS(10, 10)
      DEVOUT("Hello there", "BG+/B"))
      //
      @ 10, 10 SAY "Hello there" COLOR "BG+/B"

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  DEVPOS()
  Move the cursor or printhead to a new position depending on the
  current device

  Syntax

      DEVPOS(<nRow>, <nCol>) --> NIL

  Arguments

      <nRow> and <nCol> are the new row and column positions of the
      cursor or printhead.

  Returns

      DEVPOS() always returns NIL.

  Description

      DEVPOS() is an environment function that moves the screen or printhead
      depending on the current DEVICE.  If DEVICE is SET to SCREEN, DEVPOS()
      behaves like SETPOS(), moves the cursor to the specified location, and
      updates ROW() and COL() with the new cursor position.

      If DEVICE is SET to PRINTER, DEVPOS() moves the printhead instead.
      It does this by sending the number of line feed and/or form feed
      characters to printer advancing the printhead to the new position.
      If the current SET MARGIN value is greater than zero, it is added to
      <nCol>.  The printhead is then advanced to the specified <nRow> and
      <nCol> position and PROW() and PCOL() are updated.  If either <nRow> or
      <nCol> are less than the current PROW() and PCOL() values, the
      printhead is moved according to the  following special rules:

         If <nRow> is less than PROW(), an automatic EJECT (CHR(12)) is sent
         to the printer followed by the number of line feed characters
         (CHR(10)) required to position the printhead on <nRow> of the
         following page.

         If <nCol> including the current SET MARGIN value is less than
         PCOL(), a carriage return character (CHR(13)) and the number of
         space characters required to position the printhead at <nCol> are
         sent to the printer.

      To circumvent these rules, use SETPRC() to reset PROW() and PCOL() to
      new values before using DEVPOS().  See the SETPRC() reference for more
      information.

      If the printer is redirected to a file using the SET PRINTER command,
      DEVPOS() updates the file instead of the printer.

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  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.

      DISPBEGIN() is used in concert 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() is executed, any
      pending updates are performed 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.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  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 color specified.  If <cnBoxString> is
      specified 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.

      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 \INCLUDE, is supplied with constants
      for various border configurations.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  Examples

         The following 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")

  Files:  Library is CLIPPER.LIB, header file is Box.ch.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  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 in concert with DISPBEGIN() to allow the display
      output system to buffer display updates.  This can be important for
      applications where complex screen displays are slow and the
      appearance of performance is desired.

      For more information, refer to DISPBEGIN()

  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
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  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 not specified, <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.  If you want to specify a literal color
      setting, it must be specified enclosed 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 does not follow the SET DEVICE setting; output always goes to
      the screen.

  Examples

      The following example taken from Getsys.prg demonstrates how DISPOUT()
      can be used to perform full-screen output that is not affected by the
      SET DEVICE setting.  Note how the cursor position is saved and restored
      using ROW(), COL(), and SETPOS():

      STATIC PROCEDURE ShowScoreboard
         LOCAL nRow, nCol
         IF ( SET(_SET_SCOREBOARD) )
            nRow := ROW()
            nCol := COL()
            SETPOS( SCORE_ROW, SCORE_COL )
            DISPOUT( IF(SET(_SET_INSERT), "Ins", "   ") )
            SETPOS(nRow, nCol)
         ENDIF
         RETURN

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  DOSERROR()
  Return the last DOS error number

  Syntax

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

  Arguments

      <nNewOsCode> if specified sets the value returned by DOSERROR().
      The value must 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().

      For a complete list of DOS error numbers and accompanying descriptions,
      refer to Appendix D of the Programming and Utilities book.

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  FIELDBLOCK()
  Return a set-get code block for a given field

  Syntax

      FIELDBLOCK(<cFieldName>) --> bFieldBlock

  Arguments

      <cFieldName> is the name of the field the set-get block will refer to.

  Returns

      FIELDBLOCK() returns a code block that, when evaluated, sets (assigns)
      or gets (retrieves) the value of the given field.  If <cFieldName> does
      not exist in the current work area, FIELDBLOCK() returns NIL.

  Description

      FIELDBLOCK() is a database function that builds a code block.  When
      executed with a argument, the code block created by this function
      assigns the value of the argument to <cFieldName>.  When executed
      without a argument, the code block retrieves the value of <cFieldName>.

      Note that the specified field variable is not required to exist
      when the code block is created, but must exist before the code
      block is executed.

  Notes

         Work Area: The code block returned by FIELDBLOCK() sets
         or gets the value of the specified field in whatever work area is
         current when the block is run.  For example, given work areas 1 and
         2, both containing field FName:

         SELECT 1
         FName:= "Kate"
         SELECT 2
         FName := "Cindy"
         bFName := FIELDBLOCK("FName")

         SELECT 1
         ? EVAL(bFName)      // "Kate"
         SELECT 2
         ? EVAL(bFName)      // "Cindy"

         The function FIELDWBLOCK() provides a set-get block for a field in a
         specific work area.

  Examples

      The following example compares FIELDBLOCK() to a code block created
      using the macro operator.  Note that using FIELDBLOCK() allows you to
      avoid the speed and size overhead of the macro operator:

      // Set-Get block defined using macro operator
      bSetGet := &( "{ |setVal| IF( setVal == NIL, FName, FName := setVal ) }"

      // Set-Get block defined using FIELDBLOCK()
      // bSetGet created here is the functional equivalent of bSetGet above
      bSetGet := FIELDBLOCK("FName")

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  FIELDGET()
  Retrieve the value of a field using the ordinal position of the
  field in the database structure

  Syntax

      FIELDGET(<nField>) --> valueField

  Arguments

      <nField> is the ordinal position of the field in the record
      structure for the current work area.

  Returns

      FIELDGET() returns the value of the specified field.  If <nField> does
      not correspond to the position of any field in the current database
      file, FIELDGET() returns NIL.

  Description

      FIELDGET() is a database function that retrieves the value of a field
      using its position within the database file structure rather than its
      field name.  Within generic database service functions this allows,
      among other things, the retrieval of field values without use of the
      macro operator.

  Examples

      The following example compares FIELDGET() to functionally equivalent
      code that uses the macro operator to retrieve the value of a field:

      LOCAL nField := 1, FName, FVal
      USE Customer NEW
      //
      // Using macro operator
      FName := FIELD( nField )        // Get field name
      FVal := &FName                  // Get field value

      // Using FIELDGET()
      FVal := FIELDGET( nField )      // Get field value

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  FIELDPOS()
  Return the position of a field in a work area

  Syntax

      FIELDPOS(<cFieldName>) --> nFieldPos

  Arguments

      <cFieldName> is the name of a field in the current or specified
      work area.

  Returns

      FIELDPOS() returns the position of the specified field within the
      list of fields associated with the current or specified work area.
      If the current work area has no field with the specified name,
      FIELDPOS() returns zero.

  Description

      FIELDPOS() is a database function that is the inverse of the
      FIELD() or FIELDNAME() function that returns the name of a field
      based on a specified position in the work area field list.
      FIELDPOS() is most often used in combination with the FIELDPUT()
      and FIELDGET() functions.

      Like other database functions, FIELDPOS() can be used to return the
      names of fields in any unselected work area by referring to the
      function using an alias expression.  See the example below.

  Examples

         This example demonstrates typical specification of the
         FIELDPOS() function:

         USE Customer NEW
         ? FIELDPOS("Name")                         // Result: 1
         ? FIELDGET(FIELDPOS("Name"))               // Result: Kate

         This example demonstrates how to use FIELDPOS() to return
         the position of a specified field in a unselected work area with
         an alias expression:

         USE Customer NEW
         USE Invoices NEW
         ? Customer->(FIELDPOS("Name"))             // Result: 1
         ? Customer->(FIELDGET(FIELDPOS("Name")))   // Result: Kate

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  FIELDPUT()
  Set the value of a field variable using the ordinal position of
  the field in the database structure

  Syntax

      FIELDPUT(<nField>, <expAssign>) --> valueAssigned

  Arguments

      <nField> is the ordinal position of the field in the current
      database file.

      <expAssign> is the value to assign to the given field.  The data
      type of this expression must match the data type of the designated
      field variable.

  Returns

      FIELDPUT() returns the value assigned to the designated field.  If
      <nField> does not correspond to the position of any field in the
      current database file, FIELDPUT() returns NIL.

  Description

      FIELDPUT() is a database function that assigns <expAssign> to the field
      at ordinal position <nField> in the current work area.  This function
      allows you to set the value of a field using its position within the
      database file structure rather than its field name.  Within generic
      database service functions this allows, among other things, the setting
      of field values without use of the macro operator.

  Examples

      The following example compares FIELDPUT() to functionally equivalent
      code that uses the macro operator to set the value of a field:

      // Using macro operator
      FName := FIELD(nField)       // Get field name
      FIELD->&FName := FVal        // Set field value

      // Using FIELDPUT()
      FIELDPUT(nField, FVal)       // Set field value

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  FIELDWBLOCK()
  Return a set-get code block for a field in a given work area

  Syntax

      FIELDWBLOCK(<cFieldName>, <nWorkArea>) --> bFieldWBlock

  Arguments

      <cFieldName> is the name of the field the set-get block will refer
      to specified as a character string.

      <nWorkArea> is the work area number where the field resides
      specified as a numeric value.

  Returns

      FIELDWBLOCK() returns a code block that when evaluated sets (assigns)
      or gets (retrieves) the value of <cFieldName> in the work area
      designated by <nWorkArea>.  If <cFieldName> does not exist in the
      specified work area, FIELDWBLOCK() returns NIL.

  Description

      FIELDWBLOCK() is a database function that builds a code block.  When
      evaluated with the EVAL() function, the code block first selects the
      designated <nWorkArea>.  If an argument was passed, the code block then
      assigns the value of the argument to <cFieldName>.  If no argument was
      passed, the code block retrieves the value of <cFieldName>.  The
      original work area is then re-selected before the code block returns
      control.

      Note that the specified field variable is not required to exist
      when the code block is created, but must exist before the code
      block is executed.

  Notes
         FIELDWBLOCK() is similar to FIELDBLOCK(), the difference
         being that FIELDBLOCK() does not incorporate a fixed work area into
         the set-get block.

  Examples
         The following example compares FIELDWBLOCK() to a code block
         created using the macro operator.  Note that using FIELDWBLOCK()
         allows you to avoid the speed and size overhead of the macro
         operator:

         // Set-Get block for work area 1 defined with macro operator
         bSetGet := &( "{ |setVal| IF( setVal == NIL, ;
            1->FName, 1->FName := setVal ) }" )

         // Set-Get block defined using FIELDWBLOCK()
         // bSetGet created here is the functional equivalent of bSetGet above
         bSetGet := FIELDWBLOCK("FName", 1)

         Another example of FIELDWBLOCK() can be found in TbDemo.prg,
         a sample program included with Clipper 5.0.  The TBColumn object,
         one of which represents each column in a TBrowse object, requires
         among its instance variables a block to retrieve the expression to
         be displayed.  FIELDWBLOCK() is used to create this block.  In the
         default installation, TbDemo.prg is located in the \CLIPPER5\SOURCE
         directory.

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  GETACTIVE()
  Return the currently active Get object

  Syntax

      GETACTIVE() --> objGet

  Returns

      GETACTIVE() returns the current active Get object within the current
      READ.  If there is no READ active when GETACTIVE() is called, it
      returns NIL.

  Description

      GETACTIVE() is an environment function that provides access to the
      active GET object during a READ.  The current active Get object is the
      one with input focus at the time GETACTIVE() is called.

  Examples

      The code that follows uses a WHEN clause to force control to branch to
      a special reader function.  Within this function, GETACTIVE() is used
      to retrieve the active Get object:

      @ 10, 10 GET x
      @ 11, 10 GET y WHEN MyReader()
      @ 12, 10 GET z
      READ

      // Called just before second get (above) becomes current
      FUNCTION MyReader
         LOCAL objGet               // Active Get holder
         objGet := GETACTIVE()      // Retrieve current active Get
         BarCodeRead( objGet )
         RETURN (.F.)               // Causes Get to be skipped in regular READ

  Files:  Library is CLIPPER.LIB, source code is in Getsys.prg.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  MEMVARBLOCK()
  Return a set-get code block for a given memory variable

  Syntax

      MEMVARBLOCK(<cMemvarName>) --> bMemvarBlock

  Arguments

      <cMemvarName> is the name of the variable the set-get block will
      refer to specified as a character string.

  Returns

      MEMVARBLOCK() returns a code block that when evaluated sets (assigns)
      or gets (retrieves) the value of the given memory variable.  If
      <cMemvarName> does not exist, MEMVARBLOCK() returns NIL.

  Description

      The code block created by MEMVARBLOCK() has two operations depending on
      whether an argument is passed to the code block when it is evaluated.
      If evaluated with an argument, it assigns the value of the argument to
      <cMemvarName>.  If evaluated without an argument, the code block
      retrieves the value of <cMemvarName>.

  Notes

         MEMVARBLOCK() creates set-get blocks only for variables
         whose names are known at runtime.  MEMVARBLOCK(), therefore, cannot
         be used to create set-get blocks for local or static variables.  The
         same restriction applies to creating blocks using the macro (&)
         operator.

  Examples

      The following example compares MEMVARBLOCK() to a code block created
      using the macro (&) operator.  Note that using MEMVARBLOCK() allows you
      to avoid the speed and size overhead of the macro operator:

      PRIVATE var := "This is a string"
      //
      // Set-Get block defined using macro operator
      bSetGet := &( "{ |setVal| IF( setVal == NIL, var, var := setVal ) }" )

      // Set-Get block defined using MEMVARBLOCK()
      // bSetGet created here is the functional equivalent of bSetGet above
      bSetGet := MEMVARBLOCK("var")

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  MLCTOPOS()
  Return byte position of a formatted string based on line and column
  position

  Syntax

      MLCTOPOS(<cText>, <nWidth>, <nLine>,
         <nCol>, [<nTabSize>], [<lWrap>]) --> nPosition

  Arguments

      <cText> is the text string to scan.

      <nWidth> is the line length formatting width.

      <nLine> is the line number counting from 1.

      <nCol> is the column number counting from 0.

      <nTabSize> is the number of columns between tab stops.  If not
      specified, the default is 4.

      <lWrap> is the word wrap flag.  If not specified, the default
      is true (.T.).

  Returns

      MLCTOPOS() returns the byte position within <cText> counting from 1.

  Description

      MLCTOPOS() is a memo function that determines the byte position
      that corresponds with a particular line and column within the
      formatted text.  Note that the line number is one-relative, the
      column number is zero-relative.  This is compatible with
      MEMOEDIT().  The return value is one-relative, making it suitable
      for use in SUBSTR() or other string functions.

      MLCTOPOS() is used in combination with MPOSTOLC() to create search
      routines or other text processing for MEMOEDIT().  Refer to the
      source code for the program editor (PE) found in
      \CLIPPER5\SOURCE\PE directory.

  Examples

      This example determines the byte position of line 5, column 3 in
      the cText string:

      cText := "Note the side on which the bread is buttered."
      //
      ? MLCTOPOS(cText, 5, 3, 0)                // Result: 10

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  MPOSTOLC()
  Return line and column position of a formatted string based on a
  specified byte position

  Syntax

      MPOSTOLC(<cText>, <nWidth>, <nPos>,
         [<nTabSize>], [<lWrap>]) --> aLineColumn

  Arguments

      <cText> is a text string.

      <nWidth> is line length formatting width.

      <nPos> is the byte position within text counting from one.

      <nTabSize> is the number of columns between tab stops.  If not
      specified, the default is four.

      <lWrap> is the word wrap flag.  If not specified, the default
      is true (.T.).

  Returns

      MPOSTOLC() returns an array containing the line and the column
      values for the specified byte position, <nPos>.

  Description

      MPOSTOLC() is a memo function that determines the formatted line
      and column corresponding to a particular byte position within
      <cText>.  Note that the line number returned is one-relative, the
      column number is zero-relative.  This is compatible with
      MEMOEDIT().  <nPos> is one-relative, compatible with AT(), RAT(),
      and other string functions.

      MPOSTOLC() is used in combination with MLCTOPOS() to create search
      routines or other text processing for MEMOEDIT().  Refer to the
      source code for the program editor (PE) found in
      \CLIPPER5\SOURCE\PE directory.

  Examples

      This example determines, for the text string shown, the line and
      column corresponding to the tenth character of the text, assuming a
      formatting width of five columns.  A formatting width of five would
      cause each of the first three words to be placed on a line by
      itself.  The tenth character of the text is the "s" in "side."  The
      word "side" would be at the leftmost column of the third line of
      the formatted text, so the return value is {3, 0}:

      cText := "Note the side on which the bread is buttered."
      //
      aLC := MPOSTOLC(cText, 5, 10)             // Result: {3, 0}

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  NETERR()
  Determine if a network command has failed

  Syntax

      NETERR([<lNewError>]) --> lError

  Arguments

      <lNewError> if specified sets the value returned by NETERR() to
      the specified status.  <lNew> can be either true (.T.) or false
      (.F.). Setting NETERR() to a specified value allows the runtime
      error handler to control the way certain file errors are handled.
      For more information, refer to Errorsys.prg.

  Returns

      NETERR() returns true (.T.) if a USE or APPEND BLANK fails.  The
      initial value of NETERR() is false (.F.).  If the current process is
      not running under a network operating system, NETERR() always returns
      false (.F.).

  Description

      NETERR() is a network function.  It is a global flag set by USE,
      USE...EXCLUSIVE, and APPEND BLANK in a network environment.  It is used
      to test whether any of these commands have failed by returning true
      (.T.) in the following situations:

      Table 5-26: NETERR() Causes
      =======================================================================
      Command            Cause
      =======================================================================
      USE                USE EXCLUSIVE by another process
      USE...EXCLUSIVE    USE EXCLUSIVE or USE by another process
      APPEND BLANK       FLOCK() or RLOCK() of LASTREC() + 1 by another user
      =======================================================================

      NETERR() is generally applied in a program by testing it following a
      USE or APPEND BLANK command.  If it returns false (.F.), you can
      perform the next operation.  If the command is USE, you can open index
      files.  If it is APPEND BLANK, you can assign values to the new record
      with a REPLACE or @...GET command.  Otherwise, you must handle the
      error by either retrying the USE or APPEND BLANK, or terminating the
      current operation with a BREAK or RETURN.

  Examples

      This example demonstrates a typical usage of NETERR().  If the USE
      succeeds, the index files are opened and processing continues. If the
      USE fails, a message displays and control returns to nearest BEGIN
      SEQUENCE construct:

      USE Customer SHARED NEW
      IF !NETERR()
         SET INDEX TO CustNum, CustOrders, CustZip
      ELSE
         ? "File is in use by another"
         BREAK
      ENDIF

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  OS()
  Return the operating system name

  Syntax

      OS() --> cOsName

  Returns

      OS() returns the operating system name as a character string.

  Description

      OS() is an environment function that returns the name of the disk
      operating system the current workstation is operating under.  The name
      is returned in the form of the operating system name followed by the
      version number.

  Examples
      This example uses OS() to report the operating system the current
      workstation is running:

      ? OS()                 // Result: DOS 3.3

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  OUTERR()
  Write a list of values to the standard error device

  Syntax

      OUTERR(<exp list>) --> NIL

  Arguments

      <exp list> is a list of values to display and can consist of any
      combination of data types including memo.

  Returns

      OUTERR() always returns NIL.

  Description

      OUTERR() is identical to OUTSTD() with the exception that it writes to
      the standard error rather than the standard output device.  Output sent
      to the standard error device bypasses the Clipper console and output
      devices as well as any DOS redirection.  It is typically used to log
      error messages in a manner that will not interfere with the standard
      screen or printer output.

  Examples

      The following example displays an error message along with the date and
      time of occurrence to the screen:

      OUTERR("File lock failure", DATE(), TIME())

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  OUTSTD()
  Write a list of values to the standard output device

  Syntax

      OUTSTD(<exp list>) --> NIL

  Arguments

      <exp list> is a list of values to display and can consist of any
      combination of data types including memo.

  Returns

      OUTSTD() always returns NIL.

  Description

      OUTSTD() is a simple output function.  The function is similar to
      QOUT(), except that it writes to the STDOUT device (instead of to the
      Clipper console output stream).  Programs with very simple output
      requirements (e.g., that perform no full-screen input or output) can
      use this function to avoid loading the terminal output subsystems.  The
      header file Simplio.ch redefines the ? and ?? commands to use the
      OUTSTD() function.

      Since OUTSTD() sends its output to the standard output device, the
      output can be redirected using the DOS redirection symbols (>, >, |).
      This allows you redirect output from a Clipper program to a file or
      pipe.  Refer to your PC/MS-DOS documentation for more information on
      this operating system facility.

  Examples

         The following example uses OUTSTD() to display a list of
         expressions:

         OUTSTD(Name, PADR(RTRIM(City) + "," + State, 20), ZipCode)

         This example shows how redirect the output of a Clipper
         program to a new file using the DOS redirection operator (>):

         C>MYPROG > FILE.TXT

  Files:  Library is CLIPPER.LIB, header file is Simplio.ch.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  SETBLINK()
  Toggle asterisk (*) interpretation in SETCOLOR() string between
  blinking and background intensity

  Syntax

      SETBLINK([<lToggle>]) --> lCurrentSetting

  Arguments

      <lToggle> toggles the meaning of the asterisk (*) character when it is
      encountered in a SETCOLOR() string.  Specifying true (.T.) causes the
      asterisk to mean blinking and false (.F.) causes it to mean background
      intensity.  The default is true (.T.).

  Returns

      SETBLINK() returns the current setting as a logical value.

  Description

      SETBLINK() is an environment function that toggles the
      blinking/background intensity attribute and reports the current state
      of SETBLINK().  When SETBLINK() is on, characters written to the screen
      can be made to blink by including an asterisk (*) in a color string
      passed to SETCOLOR().  When SETBLINK() is off, the asterisk (*) causes
      the background color to be intensified instead.  Thus, blinking and
      background intensity attributes are not available at the same time.

      =======================================================================
      Note

      This function is meaningful only on the IBM-PC or compatible computers
      with CGA, EGA, or VGA display hardware.
      =======================================================================

  Examples

      This example saves the current SETBLINK() state before passing control
      to a user-defined function.  Upon return, SETBLINK() is restored to its
      original value:

      lOldBlink := SETBLINK()
      MyFunc()
      SETBLINK(lOldBlink)

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  SETMODE()
  Change display mode to specified number of rows and columns

  Syntax

      SETMODE(<nRows>, <nCols>) --> lSuccess

  Arguments

      <nRows> is the number of rows in the desired display mode.

      <nCols> is the number of columns in the desired display mode.

  Returns

      SETMODE() returns true (.T.) if the mode change was successful;
      otherwise, it returns false (.F.).

  Description

      SETMODE() is an environment function that attempts to change the mode
      of the display hardware to match the number of rows and columns
      specified.  The change in screen size is reflected in the values
      returned by MAXROW() and MAXCOL().

  Examples

      The following example switches to a 43-line display mode:

      IF SETMODE(43, 80)
        ? "43-line mode successfully set"
      ELSE
        ? "43-line mode not available"
      ENDIF

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  @...SAY
  Display data at a specified screen or printer row and column

  Syntax

      @ <nRow>, <nCol>
         SAY <exp> [PICTURE <cSayPicture>] [COLOR <cColorString>]

  Arguments

      <nRow> and <nCol> are the row and column coordinates of the
      display.  Row values can range from zero to a maximum of MAXROW() if
      the current DEVICE is the SCREEN or 32,766 if the current DEVICE is the
      PRINTER.  Likewise, column values can range from zero to a maximum of
      MAXCOL() or 32,766 if the current DEVICE is the PRINTER.

      SAY <exp> displays the result of an character, date, logical, or
      numeric expression to the current DEVICE.

      PICTURE <cSayPicture> defines the formatting control for the
      display of <exp>.  Clipper provides two mechanisms to control
      formatting: functions and templates.  Functions apply to the entire
      SAY, while templates format characters position by position.

      COLOR <cColorString> defines the display color of <exp>.  If
      not specified, <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.  If you
      want to specify a literal color setting, it must be specified
      enclosed in quote marks.

      On a combined @...SAY...GET command where colors are specified for
      both the SAY and the GET clause, two COLOR clauses are required;
      one for the SAY, one for the GET.

  Description

      @...SAY is a full-screen command that outputs the results of <exp> to
      either the screen or the printer at the specified row and column
      coordinates.  It can optionally format output using the PICTURE
      clause.  @...SAY is used to create data entry screens or reports that
      can be sent to the screen or printer.

      When an @...SAY command is executed, the output from <exp> is sent to
      the current device defined with SET DEVICE.  The current DEVICE can
      either be the SCREEN or PRINTER.  Unlike console commands, @...SAY
      output to the printer is not echoed to the screen and SET CONSOLE has
      no effect on @...SAY output to the screen.

      If the current DEVICE is the SCREEN (the system default), @...SAY
      displays output to the screen leaving the cursor one column position to
      the right of the last character displayed.  ROW() and COL() are then
      updated with this position.  Output that displays off the screen as
      defined by MAXROW() and MAXCOL() is clipped and the cursor is
      positioned off the visible screen.  All @...SAY output displays in
      standard color.  Refer to the SETCOLOR() reference, in the Standard
      Functions chapter in this book for more information on color.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C      If the current DEVICE is set to PRINTER, the display is directed to the
      printer at the specified <nRow> and <nCol> position.  If current MARGIN
      value is greater than zero, it is added to <nCol> first.  The printhead
      is then advanced one column position to the right of the last character
      output and PROW() and PCOL() are updated.  @...SAY commands to the
      printer behave a little differently than to the screen if output is
      addressed to a printer row or column position less than the current
      PROW() and PCOL() values.

         If <nRow> is less than PROW(), an automatic EJECT (CHR(12)) is sent
         to the printer followed by the number of line-feed characters
         (CHR(10)) required to position the printhead on <nRow> on the
         following page.

         If <nCol> including the SET MARGIN value is less than PCOL(), a
         carriage return character (CHR(13)) and the number of spaces
         required to position <exp> at <nCol> are sent to the printer.

      To override this behavior in order to send control codes to the
      printer, or for any other reason, you can use SETPRC() to reset PROW()
      and PCOL() to new values.  See the SETPRC() reference in the Standard
      Functions chapter of this book for more information.

      If the current DEVICE is the PRINTER, output from @...SAY commands can
      be re-directed to a file using the SET PRINTER TO <xcFile> command.

      As stated above, @...SAY command output can be formatted using the
      PICTURE clause with a <cSayPicture>.  This performs the same action as
      the TRANSFORM() function.  A <cSayPicture> may consist of a function
      and/or a template.  A PICTURE function imposes a rule as to how the
      @...SAY output is displayed as a whole.  A PICTURE template defines the
      length of the @...SAY output and the formatting rule for each position
      within the output.

         Function string: A PICTURE function string specifies formatting
         rules which apply to the SAY's display value as a whole, rather than
         to particular character positions within it.  The function string
         consists of the @ character, followed by one or more additional
         characters, each of which has a particular meaning (see table
         below).  If a function string is present, the @ character must be
         the left-most character of the picture string, and the function
         string must not contain spaces.  A function string may be specified
         alone or with a template string.  If both are present, the function
         string must precede the template string, and the two must be
         separated by a single space.

         Table 4-3: SAY and TRANSFORM() PICTURE Format Functions
         ===================================================================
         Function     Action
         ===================================================================
         B            Displays numbers left-justified
         C            Displays CR after positive numbers
         D            Displays dates in SET DATE format
         E            Displays dates and numbers in British format
         R            Non-template characters are inserted
         X            Displays DB after negative numbers
         Z            Displays zeros as blanks
         (            Encloses negative numbers in parentheses
         !            Converts alphabetic characters to upper case
         ===================================================================
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C         Template string: A PICTURE template string specifies formatting
         rules on a character by character basis.  The template string
         consists of a series of characters, some of which have special
         meanings (see table below).  Each position in the template string
         corresponds to a position in the displayed SAY value.  Characters in
         the template string which do not have assigned meanings are copied
         verbatim into the displayed SAY value.  If the @R picture function
         is used, these characters are inserted between characters of the
         display value; otherwise, they overwrite the corresponding
         characters of the display value.  A template string may be specified
         alone or with a function string.  If both are present, the function
         string must precede the template string, and the two must be
         separated by a single space.

         Table 4-4: SAY and TRANSFORM() Template Symbols
         ======================================================================
         Template        Action
         ======================================================================
         A,N,X,9,#       Displays digits for any data type
         L               Displays logicals as "T" or "F"
         Y               Displays logicals as "Y" or "N"
         !               Converts alphabetic character to upper case
         $               Display a dollar sign in place of a leading space
                         in a number
         *               Display an asterisk in place of a leading space
                         in a number
         .               Specifies a decimal point position
         ,               Specifies a comma position
         ======================================================================

  Examples

         The following example demonstrates using @...SAY with a PICTURE
         clause to display formatted output:

         nNetIncome = 7125.50
         nNetLoss = -125.50
         cPhone = "2134567890"
         cName = "Kate Mystic"
         //
         @ 1, 1 SAY nNetIncome PICTURE "@E 9,999.99"  //Result: 7,125.50
         @ 2, 1 SAY nNetLoss PICTURE "@)"             //Result: (125.50)
         @ 3, 1 SAY cPhone PICTURE "@R (999)999-9999" //Result: (213)456-7890
         @ 4, 1 SAY cName PICTURE "@!"                //Result: KATE MYSTIC

         This example is a small label printing program that uses SET DEVICE
         to direct output to the printer and SETPRC() to suppress automatic
         EJECTs:

         USE Salesman INDEX Salesman NEW
         SET DEVICE TO PRINTER
         DO WHILE !EOF()                            // Print all records
            @ 2, 5 SAY RTRIM(FirstName) + " " + LastName
            @ 3, 5 SAY Street
            @ 4, 5 SAY RTRIM(City) + ", " + State + "  " + PostalCode
            @ 6, 0 SAY SPACE(1)                     // Move to label bottom
            SETPRC(0, 0)                            // Suppress page eject
            SKIP                                    // Next record
         ENDDO
         SET DEVICE TO SCREEN
         CLOSE Salesman

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  @...TO
  Draw a single or double line box

  Syntax

      @ <nTop>, <nLeft>
         TO <nBottom>, <nRight> [DOUBLE] [COLOR <cColorString>]

  Arguments

      <nTop>, <nLeft>, <nBottom>, and <nRight> define the coordinates
      of the box.  @...TO will draw using row values from zero to MAXROW()
      and column values from zero to MAXCOL().  <nBottom> and <nRight> can be
      larger than the screen size but output is clipped at MAXROW() and
      MAXCOL().

      DOUBLE draws the box with a double line.  If not specified, the box
      is drawn with a single line.

      COLOR <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().
      Note that <cColorString> is a character expression containing the
      standard color setting.  If you want to specify a literal color
      setting, enclose it within quote marks.

  Description

      @...TO draws a single or double line box on the screen.  If <nTop> and
      <nBottom> are the same, a horizontal line is drawn.  If <nLeft> and
      <nRight> are the same, a vertical line is drawn.

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

      @...TO is similar to @...BOX with the exception that @...BOX allows you
      to define the characters of the box and supports a fill character.
      @...TO, however, is recommended for portability since it does not
      require the specification of hardware-dependent graphics characters.

  Examples

      The following example erases a region of the screen and then draws a
      box of the same size:

      @ 10, 10 CLEAR TO 20, 40
      @ 10, 10 TO 20, 40 DOUBLE COLOR "BG+/B"

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  DISPLAY
  Display records to the console

  Syntax

      DISPLAY <exp list>
         [TO PRINTER] [TO FILE <xcFile>]
         [<scope>] [WHILE <lCondition>] [FOR <lCondition>] [OFF]

  Arguments
      <exp list> is the list of values to display for each record
      processed.

      TO PRINTER echoes output to the printer.

      TO FILE echoes output to <xcFile> which can be specified either as
      a literal filename or as a character expression enclosed in
      parentheses.  If an extension is not specified, (.txt) is added.
      <scope> is the portion of the current database file to DISPLAY.
      The default is the current record, or NEXT 1.  If a condition is
      specified, the scope becomes ALL.

      WHILE <lCondition> specifies the set of records meeting the
      condition from the current record until the condition fails.
      FOR <lCondition> specifies the conditional set of records to
      DISPLAY within the given scope.
      OFF suppresses the display of the record number.

  Description
      DISPLAY is a database command that sequentially accesses records in the
      current work area sending the results of the <exp list> to the console
      in a tabular format with each column separated by a space.  The command
      does not display column headers or pause at predetermined intervals.
      DISPLAY is identical to LIST with the exception that its default scope
      is NEXT 1 rather than ALL.

      When invoked, output is sent to the screen and optionally to the
      printer and/or a file.  To suppress output to the screen while printing
      or echoing output to a file, SET CONSOLE OFF before the DISPLAY
      command-line.

  Notes
         Interrupting output: To allow the user to interrupt the
         processing of a DISPLAY command, add a test for the interrupt key
         press to FOR condition using the INKEY() function.  See the example
         below.
         Printer margin: Since DISPLAY is a console command, it honors
         the current SET MARGIN for output echoed to the printer.

  Examples
         This example illustrates a simple DISPLAY, and a conditional DISPLAY
         to the printer.

         USE Sales NEW
         DISPLAY DATE(), TIME(), Branch
         DISPLAY Branch, Salesman FOR Amount > 500 TO PRINTER

         This example demonstrates how to interrupt a DISPLAY using INKEY()
         to test if the user pressed the Esc key:
         #define K_ESC 27
         USE Sales INDEX SalesMan NEW
         DISPLAY Branch, Salesman, Amount WHILE INKEY() != K_ESC

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  INPUT
  Enter the result of an expression into a variable

  Syntax

      INPUT [<expPrompt>] TO <idVar>

  Arguments

      <expPrompt> is an optional prompt displayed before the input area.
      The prompt can be an expression of any data type.

      TO <idVar> specifies the name of the variable to assign the
      evaluation result.  If <idVar> is not visible or does not exist, a
      private variable is created and assigned the result.

  Description

      INPUT is a console command and wait state that takes entry from the
      keyboard in the form of a legal expression up to 255 characters and any
      data type.  When invoked, INPUT sends a carriage return/line feed to
      the screen, displays the prompt, and begins accepting keyboard input at
      the first character position following the prompt.  Input greater than
      MAXCOL() wraps to the next line.

      Pressing Return terminates entry of the expression.  The expression is
      then compiled and evaluated using the macro (&) operator, and the
      result assigned to <idVar>.  If the variable is not visible or does not
      exist, it is created as a private.  If no expression is entered, no
      action is taken.

      INPUT supports only two special keys: Backspace and Return.  Esc is not
      supported.  Backspace deletes the last character typed.  Return
      confirms entry and is the only key that can terminate an INPUT.

  Examples

      This example demonstrates INPUT assigning to an existing local
      variable:

      LOCAL exp
      INPUT "Expression: " TO exp
      IF exp != NIL
         ? exp
      ELSE
         ? "No expression entered"
      ENDIF

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  LIST
  List records to the console

  Syntax

      LIST <exp list>
         [TO PRINTER] [TO FILE <xcFile>]
         [<scope>] [WHILE <lCondition>] [FOR <lCondition>] [OFF]

  Arguments

      <exp list> is the list of expressions to be evaluated and displayed
      for each record processed.

      TO PRINTER echoes output to the printer.

      TO FILE <xcFile> echoes output to the specified filename and can be
      specified either as a literal filename or as a character expression
      enclosed in parentheses.  If an extension is not specified, (.txt) is
      added.

      <scope> is the portion of the current database file to LIST.  The
      default is ALL records.

      WHILE <lCondition> specifies the set of records meeting the
      condition from the current record until the condition fails.

      FOR <lCondition> specifies the conditional set of records to LIST
      within the given scope.

      OFF suppresses the display of record numbers.

  Description
      LIST is a console command that sequentially accesses records in the
      current work area, displaying the results of one or more expressions
      for each record accessed.  The output is in tabular format with each
      column separated by a space.  LIST is identical to DISPLAY with the
      exception that its default scope is ALL rather than NEXT 1.
      When invoked, output is sent to the screen and optionally to the
      printer and/or a file.  To suppress output to the screen while printing
      or echoing output to a file, SET CONSOLE OFF before the LIST
      invocation.

  Notes
         Interrupting LIST: To allow the user to interrupt a LIST, use
         INKEY() as a part of the FOR condition to test for an interrupt key
         press.  See the example below.
         Printer margin: LIST honors the current SET MARGIN for output
         echoed to the printer.

  Examples
         In this example, a simple list is followed by a conditional list to
         the printer:
         USE Sales
         LIST DATE(), TIME(), Branch
         LIST Branch, Salesman FOR Amount > 500 TO PRINTER

         This example demonstrates how to interrupt LIST using INKEY() to
         test if the user pressed the Esc key:
         #define  K_ESC    27
         USE Sales INDEX Salesman NEW
         LIST Branch, Salesman, Amount WHILE INKEY() != K_ESC

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  SET ALTERNATE
  Echo console output to a text file

  Syntax
      SET ALTERNATE TO [<xcFile> [ADDITIVE]]
      SET ALTERNATE on | OFF | <xlToggle>

  Arguments
      TO <xcFile> opens a standard ASCII text file for output with a
      default extension of (.txt).  The filename may optionally include an
      extension, drive letter, and/or path.  <xcFile> may be specified either
      as a literal filename or as a character expression enclosed in
      parentheses.  Note that if a file with the same name exists, it is
      overwritten.

      ADDITIVE causes the specified alternate file to appended to
      instead of overwritten.  If not specified, the specified alternate
      file is truncated before new information is written to it.

      ON causes console output to be written to the open text file.

      OFF discontinues writing console output to the text file without
      closing the file.

      <xlToggle> is a logical expression that must be enclosed in
      parentheses.  A value of true (.T.) is the same as ON, and a value of
      false (.F.) is the same as OFF.

  Description
      SET ALTERNATE is a console command that allows you to write the output
      of console commands to a text file.  Commands such as LIST, REPORT
      FORM, LABEL FORM, and ? that display to the screen without reference to
      row and column position are console commands.  Most of these commands
      have a TO FILE clause that performs the same function as SET
      ALTERNATE.  Full-screen commands such as @...SAY cannot be echoed to a
      disk file using SET ALTERNATE.  Instead you can use SET PRINTER TO
      <xcFile> in combination with SET DEVICE TO PRINTER to accomplish this.

      SET ALTERNATE has two basic forms.  The TO <xcFile> form creates a DOS
      text file with a default extension of (.txt) and overwrites any other
      file with the same name.  Alternate files are not related to work areas
      with only one file open at a time.  To close an alternate file, use
      CLOSE ALTERNATE, CLOSE ALL, or SET ALTERNATE TO with no argument.

      The on|OFF form controls the writing of console output to the current
      alternate file.  SET ALTERNATE ON begins the echoing of output to the
      alternate file.  SET ALTERNATE OFF suppresses output to the alternate
      file but does not close it.

  Examples
      This example creates an alternate file and writes the results of the ?
      command to the file for each record in the Customer database file:
      SET ALTERNATE TO Listfile
      SET ALTERNATE ON
      USE Customer NEW
      DO WHILE !EOF()
         ? Customer->Lastname, Customer->City
         SKIP
      ENDDO
      SET ALTERNATE OFF
      CLOSE ALTERNATE
      CLOSE Customer

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  SET PRINTER
  Toggle echo of console output to the printer or set the destination of
  printed output

  Syntax

      SET PRINTER on | OFF | <xlToggle>
      SET PRINTER TO [<xcDevice> | <xcFile> [ADDITIVE]]

  Arguments

      ON echoes console output to the printer.

      OFF suppresses the printing of console output.

      <xlToggle> is a logical expression that must be enclosed in
      parentheses.  A value of true (.T.) is the same as ON, and a value of
      false (.F.) is the same as OFF.

      TO <xcDevice> identifies the name of the device where all
      subsequent printed output will be sent.  A device name can be specified
      as a literal character string or a character expression enclosed in
      parentheses.  Additionally, a device can be either local or network.
      SETting PRINTER TO a non-existing device creates a file with the name
      of the device.  When specifying device names, be sure not to use a
      trailing colon.

      TO <xcFile> identifies the name of the output file.  The filename
      can be specified as a literal string or as a character expression
      enclosed in parentheses.  If a file extension is not specified, (.prn)
      is assumed.

      ADDITIVE causes the specified output file to appended to
      instead of overwritten.  If not specified, the specified output
      file is truncated before new information is written to it.  The
      ADDITIVE clause is only meaningful when SETting PRINTER TO a output
      file.

      If SET PRINTER TO is specified with no arguments, the specified device
      or file is closed and the default destination is then re-selected.

  Description

      SET PRINTER, like many other SET commands, has two basic forms with
      each having its own functionality.  The on|OFF form of SET PRINTER
      controls whether the output of console commands is echoed to the
      printer.  Console commands generally are commands that do not specify
      row and column coordinates.  All of these commands, except ?|??, have a
      TO PRINTER clause that also directs output to the printer.  Output from
      console commands is displayed to the screen unless CONSOLE is OFF.  Be
      aware that @...SAYs are not affected by SET PRINTER ON.  To send them
      to the printer, use SET DEVICE TO PRINTER instead.

      SET PRINTER TO, by contrast, determines the destination of output from
      all commands and functions that send output to the printer.  This
      includes @...SAYs if DEVICE is SET TO PRINTER.  Output can either be
      sent to a device or a file.  If the destination is a device, the
      following names are valid: LPT1, LPT2, LPT3 (all parallel ports), COM1,
      and COM2 (serial ports), CON and PRN.  The default device is PRN.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C      If the destination is a file, it is created in the current DEFAULT
      directory.  If a file with the same name exists in the same location,
      it is overwritten by the new file without warning.  All subsequent
      output to the printer is then written to this file until closed using
      SET PRINTER TO with no argument.

      There are a number of uses for SET PRINTER TO including:

         Managing multiple printers by swapping ports

         Directing output to a file for printing later or for transferring to
         a remote computer via telecommunications

         Emptying the printer spooler and resetting the default device

  Notes
         Compatibility: Clipper does not support the syntax SET PRINTER
         TO \\SPOOLER or \\CAPTURE.  Specifying SET PRINTER with either of
         these options creates the files Spooler.prn or Capture.prn.  The
         symbols \\ are ignored.
         End-of-file marks: When printer output is redirected to a file,
         an end-of-file mark (CHR(26)) is not written when the file is
         closed.  To terminate a file with an end-of-file mark, issue a ??
         CHR(26) just before the SET PRINTER command that closes the file.
         Networking: For some networks, the workstation's printer should
         first be redirected to the file server (usually by running the
         network spooler program).

  Examples

         This example echoes the output of the ? command to printer,
         suppressing the console screen display by SETting CONSOLE OFF:
         USE Customer NEW
         SET PRINTER ON
         SET CONSOLE OFF
         DO WHILE !EOF()
            ? Customer->Name, Customer->Phone
            SKIP
         ENDDO
         EJECT
         SET PRINTER OFF
         SET CONSOLE ON
         CLOSE
         RETURN

         This example directs printer output to LPT1 and empties the print
         spooler upon completion:
         SET PRINTER TO LPT1
         <Printing statements>...
         SET PRINTER TO                  // Empty the print spooler

         The following example sends printer output to a text file
         overwriting an existing file with the same name:
         SET PRINTER TO Prnfile.txt
         SET DEVICE TO PRINTER
         SET PRINTER ON
         //
         @ 0, 0 SAY "This goes to Prnfile.txt"
         ? "So will this!"
         //
         SET DEVICE TO SCREEN
         SET PRINTER OFF
         SET PRINTER TO                  // Close the print file

  Files:  Library is CLIPPER.LIB.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  USE
  Open an existing (.dbf) and its associated files

  Syntax

      USE [<xcDatabase>
         [INDEX <xcIndex list>]
         [ALIAS <xcAlias>] [EXCLUSIVE | SHARED]
         [NEW] [READONLY]
         [VIA <cDriver>]]

  Arguments

      <xcDatabase> is the name of the database file to open and may be
      specified either as a literal filename or as a character expression
      enclosed in parentheses.

      INDEX <xcIndex list> specifies the name(s) of up to 15 index files
      to open in the current work area.  Each index may be specified either
      as a literal filename or as a character expression enclosed in
      parentheses with the first index in the list becoming the controlling
      index.  If an <xcIndex> is specified as an expression and the value
      returned is spaces or NIL, it is ignored.

      ALIAS <xcAlias> is the name to associate with the work area when
      the database file is opened.  The alias name may be specified either
      as a literal name or as a character expression enclosed in parentheses.
      If this clause is not specified, the alias defaults to the database
      filename.

      EXCLUSIVE opens the database file for non-shared use in a network
      environment.  All other users are denied access until the database file
      is CLOSEd.

      SHARED opens the database file for shared use in a network
      environment.  Specifying this clause overrides the current EXCLUSIVE
      setting.

      NEW opens <xcDatabase> in the next available work area making it
      the current work area.  If this clause is not specified, <xcDatabase>
      is opened in the current work area.

      READONLY opens <xcDatabase> with a read-only attribute.  This
      allows you to open database files marked read-only.  If the
      <xcDatabase> can not be opened in this way, a runtime error is
      generated.  If this clause is not specified, <xcDatabase> is opened
      read-write.

      VIA <cDriver> defines the replaceable database driver (RDD) to
      use to process the current work area.  <cDriver> is name of the RDD
      specified as a character expression.  If <cDriver> is specified as
      a literal value, it must be enclosed in quotes.

      If the VIA clause is not specified, the DBFNTX driver is used by
      default.  Note that if the specified driver is not linked, an
      unrecoverable error occurs.

      In no arguments are specified, the database file open in the current
      work area is closed.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  Description

      USE opens an existing database (.dbf) file, its associated memo (.dbt)
      file, and optionally associated index (.ntx or .ndx) file(s) in the
      current or the next available work area.  In Clipper, there are 250
      work areas with a maximum of 255 total files open in DOS 3.3 and
      above.  Before USE opens a database file and its associated files, it
      closes any active files already open in the work area.  When a database
      file is first opened, the record pointer is positioned at the first
      logical record in the file (record one if there is no index file
      specified).

      In a network environment, database files can be opened EXCLUSIVE or
      SHARED.  EXCLUSIVE precludes the USE of the database file by other
      users until the file is closed.  SHARED allows other users to USE the
      database file for concurrent access.  If the database file is SHARED,
      responsibility for data integrity falls upon the application program.
      In Clipper, FLOCK() and RLOCK() are the two basic means for denying
      other users access to a particular work area or record.  If a USE is
      specified and neither EXCLUSIVE nor SHARED are specified, the database
      file is opened according to the current EXCLUSIVE setting.  In Clipper
      5.0, all USE commands should explicitly specify how the database file
      is to be opened, EXCLUSIVE or SHARED.  The implicit open mode specified
      by SET EXCLUSIVE is supplied for compatibility purposes only and
      therefore not recommended.

      Opening a database file in a network environment requires some special
      handling to be successful.  First, attempt to USE the database file
      without specifying the INDEX list.  Then, test for the success of the
      operation using NETERR().  If NETERR() returns false (.F.), the open
      operation succeeded and you can SET INDEX TO the index list.  A USE
      will fail in a network environment if another user has EXCLUSIVE USE of
      the database file.  Refer to the Network Programming chapter in the
      Programming and Utilities book for more information on opening files in
      a network environment.

      Index files can be opened either with USE or SET INDEX.  The first
      index in the list of indexes defines the current ordering of records
      when they are accessed.  This index is referred to as the controlling
      index.  The current controlling index can be changed without closing
      any files using the SET ORDER command.

      To close a database and its associated files in the current work area,
      specify USE or CLOSE with no arguments.  To close database files in all
      work areas, use CLOSE DATABASEs.  To close index files in the current
      work area without closing the database file, use CLOSE INDEX or SET
      INDEX TO with no arguments.

      Refer to the Database System section of the Basic Concepts chapter of
      this book for more information about the Clipper database paradigm.

  Notes
         Setting the maximum open files: Control of the number of file
         handles available to a Clipper application is controlled by a
         combination of the CONFIG.SYS FILES command, and the F parameter of
         the CLIPPER environment variable.  The F parameter specifies the
         maximum number of files that can be open at any one time within the
         current Clipper program.  Clipper determines the number of files
         that can be opened using the smaller of the two parameters.  For
         example, if the FILES command is set to 120 and the F parameter is
         set to 50, the maximum number of files that can be opened is 50.
         The ideal F value is 5 greater than specified with the FILES command
         and an odd number.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C         The file limit is controlled by the operating system.  With DOS
         versions less than 3.3, the maximum number of files that can be
         opened at one time is 20 files.  In DOS versions 3.3 and greater,
         the maximum limit is 255 files.

         Opening the same database file in more than one work area:
         Although opening a database file in more than one work area is
         possible in a network environment, this practice is strongly
         discouraged.

  Examples

         The following example demonstrates how to open a shared database
         file with associated index files in a network environment.  If the
         NETERR() returns false (.F.) indicating the USE was successful, the
         indexes are opened:

         USE Accounts SHARED NEW
         IF !NETERR()
            SET INDEX TO AcctNames, AcctZip
         ELSE
            ? "File open failed"
            BREAK
         ENDIF

         This example demonstrates how to open a database file with several
         indexes specified as extended expressions.  Note how the array of
         index names is created as a constant array:

         xcDatabase = "MyDbf"
         xcIndex = {"MyIndex1", "MyIndex2", "MyIndex3"}
         USE (xcDatabase) INDEX (xcIndex[1]), (xcIndex[2]), (xcIndex[3])

  Files:  Library is CLIPPER.LIB.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  BEGIN SEQUENCE
  Define a sequence of statements for a BREAK

  Syntax

      BEGIN SEQUENCE
         <statements>...
      [BREAK [<exp>]]
         <statements>...
      [RECOVER [USING <idVar>]]
         <statements>...
      END [SEQUENCE]

  Arguments

      BREAK <exp> branches execution to the statement immediately
      following the nearest RECOVER statement if one is specified or the
      nearest END SEQUENCE statement.  <exp> is the value returned into the
      <idVar> specified in the USING clause of the RECOVER statement.

      RECOVER USING <idVar> defines a recover point in the SEQUENCE
      construct where control branches after a BREAK statement.  If USING
      <idVar> clause is specified, <idVar> receives the value returned by the
      BREAK statement.  In general, this is an error object.

      END defines the end point of the SEQUENCE control structure.  If no
      RECOVER statement is specified, control branches to the first statement
      following the END statement after a BREAK.

  Description

      BEGIN SEQUENCE...END is a control structure that can be used for
      exception and runtime error handling.  It delimits a block of
      statements including invoked procedures and user-defined functions.
      When a BREAK is encountered anywhere in a block of statements following
      the BEGIN SEQUENCE statement up to the corresponding RECOVER statement,
      control branches to the program statement immediately following the
      RECOVER statement.  If a RECOVER statement is not specified, control
      branches to the statement following the END statement, terminating the
      SEQUENCE.  If control reaches a RECOVER statement without encountering
      a BREAK, it branches to the statement following the corresponding END.

      The RECOVER statement optionally receives a parameter passed by a BREAK
      statement specified with a return value.  This is most often an error
      object generated and returned by the current error handling block
      defined by ERRORBLOCK().  If an error object is returned, it can be
      sent messages to query information about the error.  With this
      information, a runtime error can be handled within the context of the
      operation rather than in the current runtime error handler.  See the
      example below.

      Within a SEQUENCE construct there are some restrictions on what
      statements are allowed between the BEGIN SEQUENCE and RECOVER
      statements.  You cannot RETURN, LOOP, or EXIT between a BEGIN SEQUENCE
      and RECOVER statement.  From within the RECOVER statement block,
      however, you can LOOP, EXIT, BREAK, or RETURN since the SEQUENCE is
      essentially completed at that point.  Using LOOP from with the RECOVER
      statement block is useful for re-executing the SEQUENCE statement
      block.  See the example below.

      SEQUENCE constructs are quite flexible.  They can be nested and more
      than one can be defined in the same procedure or user-defined
      function.  If more than one SEQUENCE construct is specified, each
      SEQUENCE should delimit one discrete operation.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C
      For more information on using BEGIN SEQUENCE to handle exceptions and
      runtime errors, refer to the Runtime Error Handling chapter in the
      Programming and Utilities book.  For more information on error objects,
      refer to the Error Class reference in the Standard Classes chapter of
      this book.

  Examples

         This code fragment demonstrates a SEQUENCE construct in which the
         BREAK occurs within the current procedure:

         BEGIN SEQUENCE
            <statements>...
            IF lBreakCond
               BREAK
            ENDIF
         RECOVER
            <recovery statements>...
         END

         <recovery statements>...

         The following example demonstrates how an error object is returned
         from an error handler to the variable specified in the USING clause
         of the RECOVER statement:

         LOCAL objLocal, bLastHandler
         //
         // Save current and set new error handler
         bLastHandler := ERRORBLOCK({ |objErr| MyHandler(objErr, .T.) })
         //
         BEGIN SEQUENCE
            .
            . <operation that might fail>
            .
         RECOVER USING objLocal
            //
            // Send messages to objLocal and handle the error
            ? "Error: "
            IF objLocal:genCode != 0
               ?? objLocal:description
            ENDIF
            .
            .
            .
         END
         //
         // Restore previous error handler
         ERRORBLOCK( bLastHandler )

         FUNCTION MyHandler( objError, lLocalHandler )
            //
            // Handle locally returning the error object
            IF lLocalHandler
               BREAK objError
            ENDIF
            .
            . <other statements to handle the error>
            .
            RETURN NIL
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C
         This example demonstrates how a SEQUENCE statement block can be
         re-executed by LOOPing from within the RECOVER statement block:

         DO WHILE .T.
            BEGIN SEQUENCE
               .
               . <operation that may fail>
               .
            RECOVER
               IF PrintRecover()
                  LOOP                 // Repeat the SEQUENCE statement block
               ENDIF
            END
            EXIT                       // Escape from the operation
          ENDDO
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  #error
  Generates a compiler error and displays a message

  Syntax

      #error [<messageText>]

  Arguments

      <messageText> is the text of the message that you want to display.
      <messageText> is a literal character string--do not enclose the message
      in quotations unless you want them to appear as part of the display.

  Description

      #error causes the compiler to generate error number 2074.  If the
      <messageText> parameter is specified, an error message is displayed.

  Examples

      #error [<messageText>]

      The following example displays an error message based on whether or not
      a NETWORK identifier has been defined:

      #ifdef NETWORK
         #error Network version not implemented.
      #endif
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  #xcommand | #xtranslate
  Specify a user-defined command or translation directive

  Syntax

      #xcommand   <matchPattern> => <resultPattern>
      #xtranslate <matchPattern> => <resultPattern>

  Arguments

      <matchPattern> is the pattern to match in the input text.

      <resultPattern> is the text that is produced if a piece of input
      text matches the <matchPattern>.

  Description

      The #xcommand and #xtranslate directives work like #command and
      #translate except that the four letter abbreviation rules used by
      #command and #translate do not apply.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   osCode

      Contains an integer numeric value representing the operating system
      error code associated with the error condition.  A value of zero
      indicates that the error condition was not caused by an error from
      the operating system.  When Error:osCode is set to a value other
      than zero DOSERROR() is updated with the same value.

      Error:osCode properly reflects the DOS extended error code for file
      errors.  This allows proper distinction between errors which result
      from sharing violations (e.g. opening EXCLUSIVE when another
      process has already opened the file) and access violations (e.g.
      opening read/write when the file is marked read-only).

      The DOS error codes are listed in appendix D of the Programming and
      Utilities guide.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   severity

      Contains a numeric value indicating the severity of the error
      condition.  Four standard values are defined in Error.ch:

      Table: Error:severity Values
      =================================================================
      Error.ch         Meaning
      =================================================================

      ES_WHOCARES      The condition does not represent a failure; the
                       error is informational.

      ES_WARNING       The condition does not prevent further
                       operations, but may result in a more serious
                       error later.

      ES_ERROR         The condition prevents further operations
                       without corrective action of some kind.

      ES_WHOCARES      The condition does not represent a failure; the
                       error is informational.

      ES_WARNING       The condition does not prevent further
                       operations, but may result in a more serious
                       error later.

      ES_ERROR         The condition prevents further operations
                       without corrective action of some kind.

      ES_CATASTROPHIC  The condition requires immediate termination
                       of the application.
      =================================================================

      Note that the Clipper runtime support code only generates errors
      with severities of ES_WARNING or ES_ERROR.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C

 ErrorNew() --> objError

      Returns a new Error object.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   exitState  (Assignable)

      Contains a numeric value used in the Clipper 5.01 version of
      Getsys.prg to record the means by which a Get object was exited.

      Table: Get Exit States
      ===================================================================
      Number  Getexit.ch     Meaning
      ===================================================================
      0         GE_NOEXIT      No exit attempted, prepare Get for editing
      1         GE_UP          Goto previous Get
      2         GE_DOWN        Goto next Get
      3         GE_TOP         Goto first Get
      4         GE_BOTTOM      Goto last Get
      5         GE_ENTER       Get edit normal end
      6         GE_WRITE       Terminate READ state with Get save
      7         GE_ESCAPE      Terminate READ state without Get save
      8         GE_WHEN        WHEN clause unsatisfied
      ==================================================================

      Manifest constants for the Get:exitState values can be found in
      Getexit.ch.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   subscript

      Contains a numeric value or array that gives information about
      array Get objects.  On a GET of a single-dimensional array element,
      Get:subscript contains a numeric value representing the subscript
      used in the @...GET command.

      On a GET of a multi-dimensional array element, Get:subscript
      contains an array of numeric values representing the subscripts
      used in the @...GET command.

      If the GET involves a regular variable, Get:subscript contains NIL.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   reader

      Contains a code block to implement special READ behaviors for any
      Get.  If Get:reader contains a code block, READMODAL() evaluates
      that block in order to READ the Get (the Get object is passed as a
      argument to the block).  The block may in turn call any desired
      function to provide custom editing of the Get object. If Get:reader
      does not contain a code block, READMODAL() uses a default read
      procedure (GetReader()) for the Get object.

      Note that Get:reader allows particular Get objects to have
      specialized READ behaviors without changing the standard
      READMODAL() function.  This preserves compatibility for Gets which
      are to be handled in the customary way and also eliminates
      potential conflicts between different extensions to the GET/READ
      system.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   colorDisp([<cColorString>]) --> self

      Get:colorDisp() is a method that changes a Get object's colors and
      redisplays it.  It is exactly equivalent to assigning Get:colorSpec
      and issuing Get:display().
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   leftVisible

      Contains a numeric value indicating the position of the leftmost
      unfrozen column visible in the browse display.  If every column is
      frozen in the display, TBrowse:leftVisible contains zero.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   rightVisible

      Contains a numeric value indicating the position of the rightmost
      unfrozen column is visible in the browse display.  If all columns
      visible in the display are frozen, TBrowse:rightVisible contains
      zero.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   insColumn(<nPos>, <objColumn>) --> objColumn

      This method allows a column object to be inserted into the middle
      of a browse.  The return value is a reference to the column object
      being inserted.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C
   delColumn(<nPos>) --> objColumn

      This new method allows a column to be deleted from a browse.  The
      return value is a reference to the column object being deleted
      allowing the column object to be preserved.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   invalidate() --> self

      TBrowse:invalidate() causes the next stabilization of the TBrowse
      object to redraw the entire TBrowse display, including headings,
      footings, and all data rows.  Note that sending this message has no
      effect on the values in the data rows; it simply forces the display
      to be updated during the next stabilization.  To force the data to
      be refreshed from the underlying data source, send the
      TBrowse:refreshAll() message.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   colWidth(<nColumn>) --> nWidth

      Returns the display width of column number <nColumn> as known to the
      browse.  If <nColumn> is out of bounds or not supplied or not a number,
      the method returns zero.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C   width   (Assignable)

      Contains a numeric value that defines the display width for the
      column.  If TBColumn:width is not explicitly set, the width of the
      column will be the greater of: 1) the length of the heading, 2) the
      length of the footing, and 3) the length of the data at the first
      evaluation of TBColumn:block.  The width of the displayed data will be
      the length at the first evaluation of TBColumn:block.

      If this instance variable is explicitly set, the width of the column
      will be TBColumn:width.  Displayed headings, footings, and data will
      all be truncated to this width when necessary.  The width of the
      displayed data will be the length at the first evaluation of
      TBColumn:block for all data types other than character.  Character
      data will be extended to TBColumn:width for display purposes.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  Description

     Getsys.prg, the standard GET/READ system, has been restructured to
     provide a cleaner platform for extensions.

     Some of the functions in the Getsys.prg have been made public so that
     they can be used when implementing customized Get readers.  These
     functions are described below.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  GetApplyKey()
  Apply a key to a Get object from within a Get reader

  Syntax
     GetApplyKey(<oGet>, <nKey>) --> NIL

  Arguments
    <oGet> is a reference to a Get object.
    <nKey> is the INKEY() value to apply to <oGet>.

  Returns

     GetApplyKey() always returns NIL.

  Description

    GetApplyKey() is a Get system function that applies an INKEY() value to
    a Get object.  Keys are applied in the default way.  That is, cursor
    movement keys change the cursor position within the Get, data keys are
    entered into the Get, etc.

     If the key supplied to GetApplyKey() is a SET KEY, GetApplyKey() will
     execute the set key and return; the key is not applied to the Get
     object.

  Notes

        Focus: The Get object must be in focus before keys are
        applied. Refer to Get:setFocus and Get:killFocus for more
        information.

        CLEAR GETS: If CLEAR GETS is executed by a SET KEY,
        Get:exitState will be set to GE_ESCAPE. In the standard system, this
        cancels the current Get without assigning the edited value and
        terminates READMODAL().

  Files:  Library is CLIPPER.LIB, source is Getsys.prg.
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  GetDoSetKey()
  Process SET KEY during Get editing

  Syntax

     GetDoSetKey(<oGet>) --> NIL

  Arguments

     <oGet> is a reference to the current Get object.
  Returns

     GetDoSetKey() always returns NIL.

  Description

     GetDoSetKey() is a Get system function that executes a SET KEY code
    block, preserving the context of the passed Get object.

     Note that the procedure name and line number passed to the SET KEY
     block are based on the most recent call to READMODAL().

     Note also that if a CLEAR GETS occurs in the SET KEY code,
     Get:exitState is set to GE_ESCAPE.  In the standard system this cancels
     the current Get object processing and terminates READMODAL().

  Files:  Library is CLIPPER.LIB, source is Getsys.prg.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  GetPostValidate()
  Post-validate the current Get object

  Syntax

     GetPostValidate(<oGet>) --> lSuccess

  Arguments

     <oGet> is a reference to the current Get object.

  Returns

    GetPostValidate() returns a logical value indicating whether the Get
    object has been post-validated successfully.

  Description

     GetPostValidate() is a Get system function that validates a Get object
     after editing, including evaluating Get:postBlock (the VALID clause) if
     present.

     The return value indicates whether the Get has been post-validated
     successfully. If a CLEAR GETS is issued during post-validation,
     Get:exitState is set to GE_ESCAPE and GetPostValidate() returns true
     (.T.).

     Note that in the default system, a Get:exitState of GE_ESCAPE cancels
     the current Get and terminates READMODAL().

  Files:  Library is CLIPPER.LIB, source is Getsys.prg.

  GetPreValidate()
&lE&aL&a155h452V*c7325h1vP&a155h5652V*c7325h1vP&a155h452V*c1h5200vP&a3830h452V*c1h5200vP&a7480h452V*c1h5200vP&a7524h5352V*t150R*r1A*b8WE*b8W0!Dd@*b8W0QDd@*b8W0T@*b8W01DL@*b8W`0DL@*b8W0ND@*rB(10U(sp16.6h8.5vsbT&k7.2029H&l5.2cL&a155h5652V
                                                                                                                                                                             
&a+5h-3V                                                                                                                                                                             &a-5h+3V&l7E&a6lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  Pre-validate a Get object

  Syntax

     GetPreValidate(<oGet>) --> lSuccess

  Arguments

     <oGet> is a reference to the current Get object.

  Returns

     GetPreValidate() returns a logical value indicating whether the Get
     object has been pre-validated successfully.

  Description

     GetPreValidate() is a Get system function that validates the Get object
     for editing, including evaluating Get:preBlock (the WHEN clause) if it
     is present.  The logical return value indicates whether the Get has
     been pre-validated successfully.

     Get:exitState is also set to reflect the outcome of the pre-validation:

     Table: Get:exitState Values
     =================================================================
     Getexit.ch          Meaning
     =================================================================
     GE_NOEXIT           Indicates pre-validation success, ok to edit
     GE_WHEN             Indicates pre-validation failure
     GE_ESCAPE           Indicates that a CLEAR GETS was issued
     =================================================================

     Note that in the default system, a Get:exitState of GE_ESCAPE cancels
     the current Get and terminates READMODAL().

  Files:  Library is CLIPPER.LIB, source file is Getsys.prg.
&k7.2029H&a91lhV
(10U(sp16.6h8.5vsbT&k7.2H&l05.200C  GetReader()
  Execute standard READ behavior for a Get object

  Syntax

     GetReader(<oGet>) --> NIL

  Arguments

     <oGet> is a reference to a Get object.

  Returns

     GetReader() always returns NIL.

  Description

     GetReader() is a Get system function that implements the standard READ
     behavior for Gets.  By default, READMODAL() uses the GetReader()
     function to read Get objects.  GetReader() in turn uses