Daily Archives: February 16, 2014

SELECT

Posted on by vivaclipper

SELECT

Change the current work area

Syntax

      SELECT <xnWorkArea> | <idAlias>

Arguments

<xnWorkArea> is the work area number between 0 and 250 inclusive. This argument is an extended expression and can be specified either as a literal number or as a numeric expression enclosed in parentheses.

<idAlias> is the name of an existing work area to SELECT if there is a database file open in that area.

Description

SELECT is a database command that changes work areas. CA-Clipper supports 250 work areas, with each work area a logical handle to an open database file and all of its attributes. You can refer to work areas with SELECT by number or by alias. The alias of a work area is automatically assigned when a database file is USEd in that work area or by using the ALIAS clause.

Work area 0 refers to the first empty or next available work area. Using this, you can SELECT 0 and USE <xcDatabase> as a method of opening database files.

Notes

. Aliased expressions: Aliased expressions are a much more powerful method of selecting new work areas than the SELECT command. Instead of SELECTing a work area, and then performing an operation for that work area, you can apply an alias to an expression that performs the operation. This is done by specifying the alias of the remote work area and the expression enclosed in parentheses. For example, to access the value of EOF() in an unselected work area, you would normally execute a series of statements like the following:

            SELECT Remote
            ? EOF()
            SELECT Main

Using the aliased expression form, these statements become:

            ? Remote->(EOF())

. USE…NEW: Instead of using SELECT0 and USE <xcDatabase> to open a database file in a new work area, the preferred method is to USE <xcDatabase> NEW.

Examples

      .  This example opens a series of database files by SELECTing
         each work area by number then USEing each database file in that
         work area:

         SELECT 1
         USE Customer
         SELECT 2
         USE Invoices
         SELECT 3
         USE Parts
         SELECT Customer

      .  A better method is to open each database in the next available
         work area by specifying the NEW clause on the USE command line.
          In this example USE...NEW is employed instead of SELECT 0 and
         then USE:

         USE Customer NEW
         USE Invoices NEW

         SELECT Customer

      .  This code fragment changes work areas while saving the current
         work area name to a variable using the SELECT() function.  After
         executing an operation for the new work area, the original work
         area is restored:

         nLastArea := SELECT()
         USE Newfile NEW
         //
         <statements>...
         //
         SELECT (nLastArea)

Seealso

ALIAS(), EOF(), SELECT(), SET INDEX, USE, USED()

SEEK

Posted on by vivaclipper

Search an order for a specified key value

Syntax

      SEEK <expSearch> [SOFTSEEK]

Arguments

<expSearch> is an expression to match with an order key value.

SOFTSEEK causes the record pointer to be moved to the next record with a higher key value after a failed order search. Default behavior moves the record pointer to EOF() after a failed order search.

Description

SEEK is a database command that searches the controlling order from the first or last key value (depending on whether the LAST keyword is specified) and proceeds until a match is found or there is a key value greater than <expSearch>. If there is a match, the record pointer is positioned to the identity found in the order. If SOFTSEEK is OFF (the default) and SEEK does not find a match, the record pointer is positioned to LASTREC() + 1, EOF() returns true (.T.), and FOUND() returns false (.F.).

SOFTSEEK enables a method of searching an order and returning a record even if there is no match for a specified key.

When SOFTSEEK is ON and a match for a SEEK is not found, the record pointer is set to the next record in the order with a higher key value than the SEEK argument. Records are not visible because SET FILTER and/or SET DELETED are skipped when searching for the next higher key value. If there is no record with a higher key value, the record pointer is positioned at LASTREC() + 1, EOF() returns true (.T.), and FOUND() returns false (.F.). FOUND() returns true (.T.) only if the record is actually found. FOUND() never returns true (.T.) for a relative find.

When SOFTSEEK is OFF and a SEEK is unsuccessful, the record pointer is positioned at LASTREC() + 1, EOF() returns true (.T.), and FOUND() returns false (.F.).

SEEK with the SOFTSEEK clause is, effectively, the same as performing SET SOFTSEEK and then SEEK in earlier versions of Clipper except that it does not change the global setting of SOFTSEEK.

Examples

      .  The following example searches for "Doe" using the SEEK
         command:

      USE Customer NEW
      SET ORDER TO Customer
      ? SET( _SET_SOFTSEEK )      // (.F.)
      SEEK "Doe"
      ? SET( _SET_SOFTSEEK )      // Still (.F.)
      IF FOUND()
         .
         . < statements >
         .
      ENDIF

      .  The following example performs a soft seek for "Doe" using
         SOFTSEEK clause of the SEEK command:

      USE Customer NEW
      SET ORDER TO Customer
      ? SET( _SET_SOFTSEEK )      // (.F.)
      SEEK "Doe" SOFTSEEK
      ? SET( _SET_SOFTSEEK )      // Still (.F.)
      IF !FOUND()
         ? Customer->Name         // Returns next logical name after "Doe"
      ENDIF

Seealso

DBSEEK(), DBSETINDEX(), DBSETORDER(), EOF(), SET INDEX

SAVE

Posted on by vivaclipper

SAVE

Save variables to a memory (.mem) file

Syntax

      SAVE TO <xcMemFile> [ALL [LIKE | EXCEPT <skeleton>]]

Arguments

<xcMemFile> is the memory (.mem) file to SAVE to disk. You may specify the file name as a literal string or as a character expression enclosed in parentheses. If you specify no extension, the file is created with a .mem extension.

ALL [LIKE|EXCEPT <skeleton>] defines the set of visible private and public memory variables to save to <xcMemFile>. <skeleton> is the wildcard mask that characterizes a group of memory variables to SAVE. The wildcard characters supported are * and ?.

Description

SAVE copies public and private memory variables visible within the current procedure or user-defined function to a memory (.mem) file. Arrays and local and static variables, however, cannot be SAVEd. When variables are SAVEd, they are copied without any reference to scope. Variables hidden by PRIVATE or LOCAL declarations are not SAVEd.

If you specify the ALL LIKE clause, variable names matching the <skeleton> mask are saved. By contrast, if you specify ALL EXCEPT, variable names not matching the <skeleton> are saved.

You can specify a <skeleton> that includes wildcard characters. The * wildcard character matches any group of adjacent characters ending a variable name and can be specified only at the end of the <skeleton>. The ? wildcard character matches any single character and can be specified anywhere within the <skeleton>.

Examples

      .  This example saves all visible private and public variables to
         Temp.mem:

         PRIVATE cOne := "1"
         SAVE ALL TO Temp

      .  This example saves all visible private and public variables
         with names beginning with "c" to Myvars.mem:

         SAVE ALL LIKE c* TO MyVars

      .  This example saves all visible private and public variables
         with names that do not begin with "c" to Myvars2.mem:

         SAVE ALL EXCEPT c* TO MyVars2

Seealso

LOCAL, PRIVATE, PUBLIC, RESTORE

RESTORE

Posted on by vivaclipper

RESTORE

Retrieve memory variables from a memory (.mem) file

Syntax

      RESTORE FROM <xcMemFile> [ADDITIVE]

Arguments

<xcMemFile> is the memory (.mem) file to load from disk. If an extension is not specified, the extension .mem is assumed. The file name may be specified as a literal string or as a character expression enclosed in parentheses.

ADDITIVE causes memory variables loaded from the memory file to be added to the existing pool of memory variables.

Description

RESTORE is a memory variable command that recreates public and private variables previously SAVEd to a memory (.mem) file and initializes them with their former values. The scope of the variable is not SAVEd with the variable, but is instead established when the variable is RESTOREd. Arrays and local variables cannot be SAVEd or RESTOREd.

When memory variables are RESTOREd, they are recreated as private variables with the scope of the current procedure or user-defined function unless they exist as public variables and you specify the ADDITIVE clause. If ADDITIVE is specified, public and private variables with the same names are overwritten unless hidden with PRIVATE. If ADDITIVE is not specified, all public and private variables are released before the memory file is loaded.

Local and static variables are unaffected by RESTORE. If a local or static variable has been declared in the current procedure or user- defined function and a variable with the same name is RESTOREd, only the local or static variable is visible unless references to the RESTOREd variable are prefaced with the MEMVAR alias.

Examples

      .  This example demonstrates a typical application of SAVE and
         RESTORE.  Here memory variables containing screens are SAVEd
         TO and RESTOREd FROM memory files:

      // Create and use a pseudoarray of screens
      SAVE SCREEN TO cScreen1
      SAVE ALL LIKE cScreen* TO Screens
      //
      <statements>...
      //
      RESTORE FROM Screens ADDITIVE
      nNumber = "1"
      RESTORE SCREEN FROM ("cScreen" + nNumber)

Seealso

LOCAL, PRIVATE, PUBLIC, SAVE

REPLACE

Posted on by vivaclipper

Assign new values to field variables

Syntax

      REPLACE <idField> WITH <exp>
            [, <idField2> WITH <exp2>...]
            [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

Arguments

<idField> is the name of the field variable to be assigned a new value. If <idField> is prefaced with an alias, the assignment takes place in the designated work area.

WITH <exp> defines the value to assign to <idField>.

<scope> is the portion of the current database file to REPLACE. The default is the current record, or NEXT 1. Specifying a condition changes the default to ALL records in the current work area.

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 REPLACE within the given scope.

Description

REPLACE is a database command that assigns new values to the contents of one or more field variables in the current record in the specified work areas. The target field variables can be character, date, logical, memo, or numeric. REPLACE performs the same function as the assignment operator (:=) except that it assumes that an unaliased reference is to a field variable. This means that you can assign new values to field variables using assignment statements provided that the field variable references are prefaced with an alias, the FIELD alias, or declared using the FIELD declaration statement.

The default scope of REPLACE is the current record unless a scope or condition is specified. If a scope or condition is specified, the replace operation is performed on each record matching the scope and/or condition.

Warning! When you REPLACE a key field, the index is updated and the relative position of the record pointer within the index is changed. This means that REPLACEing a key field with a scope or a condition may yield an erroneous result. To update a key field, SET ORDER TO 0 before the REPLACE. This ensures that the record pointer moves sequentially in natural order. All open indexes, however, are updated if the key field is REPLACEd.

In a network environment, REPLACEing the current record requires an RLOCK(). REPLACEing with a scope and/or condition requires an FLOCK() or EXCLUSIVE USE of the current database file. If a field is being REPLACEd in another work area by specifying its alias, that record must also be locked with an RLOCK(). Refer to the “Network Programming” chapter for more information.

Examples

      .  This example shows a simple use of REPLACE:

         USE Customer NEW
         APPEND BLANK
         USE Invoices NEW
         APPEND BLANK
         //
         REPLACE Charges WITH Customer->Markup * Cost,;
            Custid WITH Customer->Custid,;
            Customer->TranDate WITH DATE()

      .  This example uses assignment statements in place of the
         REPLACE command:

         FIELD->Charges := Customer->Markup * FIELD->Cost
         FIELD->Custid := Customer->Custid
         Customer->TranDate := DATE()

Seealso

COMMIT, FLOCK(), RLOCK()

RELEASE

Posted on by vivaclipper

RELEASE

Delete public and private memory variables

Syntax

      RELEASE <idMemvar list>
         RELEASE ALL [LIKE | EXCEPT <skeleton>]

Arguments

<idMemvar list> is a list of private or public variables or arrays to delete.

ALL [LIKE|EXCEPT <skeleton>] defines the set of visible private memory variables to assign, or to exclude from assignment of, a NIL value. <skeleton> is the wildcard mask to specify a group of memory variables to delete. The wildcard characters supported are * and ?.

Description

RELEASE is a memory variable command that performs one of two actions depending on how it is specified. If RELEASE is specified with <idMemvar list>, the specified public and private memory variables and/or arrays are deleted from memory. Previous hidden instances (public or private variables defined in higher-level procedures) become accessible upon termination of the procedure where the variable was originally created.

If RELEASE is specified with any form of the ALL clause, private memory variables created at the current procedure level are assigned a NIL and not deleted until the current procedure or user-defined function terminates. Public variables are unaffected by this form of the RELEASE command. To release public variables, you must RELEASE them explicitly or use CLEAR MEMORY.

Local or static variables are not affected by the RELEASE command. Local variables are released automatically when the procedure or user- defined function (where the variables were declared) terminates. Static variables cannot be released since they exist for the duration of the program.

Seealso

CLEAR MEMORY, LOCAL, PRIVATE, PUBLIC, QUIT

REINDEX

Posted on by vivaclipper

Rebuild open indexes in the current work area

Syntax

      REINDEX
            [EVAL <lCondition>]
            [EVERY <nRecords>]

Arguments

EVAL <lCondition> specifies a condition that is evaluated either for each record processed or at the interval specified by the EVERY clause. This clause is identical to the EVAL clause of the INDEX command, but must be respecified in order for the reindexing operation to be monitored since the value of <lCondition> is transient.

EVERY <nRecords> specifies a numeric expression that modifies how often EVAL is evaluated. When using EVAL, the EVERY option offers a performance enhancement by evaluating the condition for every nth record instead of evaluating each record reindexed. The EVERY keyword is ignored if no EVAL condition is specified.

Description

REINDEX is a database command that rebuilds all open indexes in the current work area. When the reindexing operation finishes, all rebuilt indexes remain open, order is reset to one, and the record pointer is positioned to the first record in the controlling index. If any of the indexes were created with SET UNIQUE ON, REINDEX adds only unique keys to the index. If any of the indexes were created using a FOR condition, only those key values from records matching the condition are added to the index.

In a network environment, REINDEX requires EXCLUSIVE USE of the current database file. Refer to the “Network Programming” chapter for more information.

Caution! REINDEX does not recreate the header of the index file when it recreates the index. Because of this, REINDEX does not help if there is corruption of the file header. To guarantee a valid index, always use INDEX ON in place of REINDEX to rebuild damaged indexes

Notes

Index key order, UNIQUE status, and the FOR condition are known to the index (.ntx) file and are, therefore, respected and maintained by REINDEX.

Examples

      .  This example REINDEXes the index open in the current work
         area:

         USE Sales INDEX Salesman, Territory NEW
         REINDEX

      .  This example REINDEXes using a progress indicator:

         USE Sales INDEX Salesman, Territory NEW
         REINDEX EVAL NtxProgress() EVERY 10
         FUNCTION NtxProgress
         LOCAL cComplete := LTRIM(STR((RECNO()/LASTREC()) * 100))
         @ 23, 00 SAY "Indexing..." + cComplete + "%"
         RETURN .T.

Seealso

INDEX, PACK, SET INDEX, USE

RECALL

Posted on by vivaclipper

Restore records marked for deletion

Syntax

      RECALL [<scope>] [WHILE <lCondition>]
             [FOR <lCondition>]

Arguments

<scope> is the portion of the current database file to RECALL. The default scope is the current record, or NEXT 1. If a condition is specified, the default 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 RECALL within the given scope.

Description

RECALL is a database command that restores records marked for deletion in the current work area. This is the inverse of the DELETE command. If DELETED is ON, RECALL can restore the current record or a specific record, if you specify a RECORD scope. Note that once you PACK a database file, all marked records have been physically removed from the file and cannot be recovered.

In a network environment, RECALLing the current record requires an RLOCK(). RECALLing several records requires an FLOCK() or EXCLUSIVE USE of the current database file. Refer to the “Network Programming” chapter for more information.

Examples

      .  This examples show the results of RECALL:

      USE Sales NEW
      //
      DELETE RECORD 4
      ? DELETED()               // Result: .T.
      //
      RECALL
      ? DELETED()               // Result: .F.

Seealso

DELETE, DELETED, FLOCK(), PACK, RLOCK(), SET DELETED

READ

Posted on by vivaclipper

READ

Activate full-screen editing mode using Get objects

Syntax

      READ [SAVE] [MENU <oMenu>] [MSG AT <nRow>, <nLeft>,
             <nRight>] [MSG COLOR <cColorString>]

Arguments

SAVE retains the contents of the current GetList after the READ terminates. Later, you can edit the same Get objects by issuing another READ. If not specified, the current GetList is assigned an empty array deleting all of the previous Get objects when the READ terminates.

MENU <oMenu> specifies an optional Topbarmenu object that, when supplied, permits menu selection during data entry.

MSG AT <nMsgRow>, <nMsgLeft>, <nMsgRight> specify the row, left, and right margins where the Get object messages appear on the screen. If omitted, messages will not appear.

MSG COLOR <cMsgColor> defines the color setting of the message area. It consists of a single foreground/background color pair.

Description

READ executes a full-screen editing mode using all Get objects created and added to the current GetList since the most recent CLEAR, CLEAR GETS, CLEAR ALL or READ commands. If there is a format procedure active, READ executes that procedure before entering the full-screen editing mode.

Within a READ, the user can edit the buffer of each Get object as well as move from one Get object to another. Before the user can enter a Get object, control passes to the associated WHEN <lPreCondition> if one has been assigned to that Get object. If <lPreCondition> returns true (.T.), the user is allowed to edit the buffer of the Get object. Otherwise, control passes to the next Get object in the GetList. Within a GET buffer, the user can edit using the full complement of editing and navigation keys. See the tables below.

When the user presses a GET exit key, control passes to the associated RANGE or VALID postcondition if one has been specified. If either condition returns true (.T.), editing of the Get object is terminated and control passes to the next Get object. Otherwise, control remains within the current Get object until a valid value is entered or the user presses the Esc key.

When the user successfully enters a value into a Get object, the associated variable is assigned the value of the Get object’s buffer.

The following tables list active keys within a READ:

      READ Navigation Keys
      -----------------------------------------------------------------------
      Key                           Action
      -----------------------------------------------------------------------
      Left arrow, Ctrl+S            Character left. Does not move cursor to
                                    previous GET.
      Right arrow, Ctrl+D           Character right.  Does not move cursor to
                                    next GET.
      Ctrl+Left arrow, Ctrl+A       Word left.
      Ctrl+Right arrow, Ctrl+F      Word right.
      Up arrow, Shift+Tab, Ctrl+E   Previous GET.
      Down arrow, Tab, Ctrl+X,      Return, Ctrl+M Next GET.
      Home                          First character of GET.
      End                           Last character of GET.
      Ctrl+Home                     Beginning of first GET.
      -----------------------------------------------------------------------

      READ Editing Keys
      -----------------------------------------------------------------------
      Key                 Action
      -----------------------------------------------------------------------
      Del, Ctrl+G         Delete character at cursor position
      Backspace, Ctrl+H   Destructive backspace
      Ctrl+T              Delete word right
      Ctrl+Y              Delete from cursor position to end of GET
      Ctrl+U              Restore current GET to original value
      -----------------------------------------------------------------------

      READ Toggle Keys
      -----------------------------------------------------------------------
      Key            Action
      -----------------------------------------------------------------------
      Ins, Ctrl+V    Toggle insert mode
      -----------------------------------------------------------------------

      READ Exit Keys
      -----------------------------------------------------------------------
      Key                           Action
      -----------------------------------------------------------------------
      Ctrl+W, Ctrl+C, PgUp, PgDn    Terminate READ saving current GET
      Return, Ctrl+M                Terminate READ from last GET
      Esc                           Terminate READ without saving current GET
      Up arrow                      Terminate READ from first GET if
                                    READEXIT()=.T.
      Down arrow                    Terminate READ from last GET if
                                    READEXIT()=.T.
      -----------------------------------------------------------------------

Notes

. Nested READs: To perform a nested READ within a SET KEY, VALID, or WHEN procedure or user-defined function, declare or create a new GetList, perform a series of @…GET statements, and then READ. When the procedure terminates, the new GetList is released and the previous GetList becomes visible again. See the example below.

. Quick keys: Pressing Home or End in quick succession goes to the first or last nonblank character in a Get object’s buffer.

. Terminating a READ: A READ is terminated by executing a BREAK, CLEAR, CLEAR GETS, or CLEAR ALL from within a SET KEY procedure or a user-defined function initiated by VALID.

. UPDATED(): If any Get object buffer was changed during the current READ, UPDATED() is set to true (.T.).

Examples

      .  This example defines several GETs then READs them:

      CLEAR
      cVar1 := cVar2 := cVar3 := SPACE(10)
      @ 10, 10 SAY "Variable one:" GET cVar1 VALID ;
            !EMPTY(cVar1)
      @ 11, 10 SAY "Variable two:" GET cVar2 ;
               WHEN RTRIM(cVar1) !=  "One"
      @ 12, 10 SAY "Variable three:" GET cVar3 VALID ;
               !EMPTY(cVar3)
      READ

      .  This example performs a nested READ within a SET KEY, WHEN, or
         VALID procedure or user-defined function:

      LOCAL cName := SPACE(10)
      @ 10, 10 GET cName VALID SubForm( cName )
      READ
      RETURN

      FUNCTION SubForm( cLookup )
         LOCAL GetList := {}         // Create new GetList
         USE Sales INDEX Salesman NEW
         SEEK cLookup
         IF FOUND()
            @ 15, 10 GET Salesman    // Add Get objects to
            @ 16, 10 GET Amount      // new GetList
            READ                     // READ from new GetList
         ENDIF
         CLOSE Sales
         RETURN .T.                  // Release new GetList

Seealso

@…GET, @…SAY, CLEAR GETS, LASTKEY(), READEXIT()

QUIT

Posted on by vivaclipper

QUIT

Terminate program processing

Syntax

      QUIT | CANCEL*

Description

QUIT and CANCEL both terminate program processing, close all open files, and return control to the operating system. Each of these commands can be used from anywhere in a program system. A RETURN executed at the highest level procedure or a BREAK, with no pending SEQUENCE, also QUITs the program.

Notes

. Return code: When a Harbour program terminates, the return code is set to 1 if the process ends with a fatal error. If the process ends normally, the return code is set to zero or the last ERRORLEVEL() set in the program.

Examples

      .  This example uses QUIT in a dialog box:
      IF DialogYesNo(10, 10, "Quit to DOS", "BG+/B,B/W", 2)
         QUIT
      ENDIF
      RETURN

Seealso

BEGIN SEQUENCE, ERRORLEVEL(), RETURN