Руководство по программированию на clipper

The less than () operator is a binary operator that compares two values of the same data type and returns true (.T.) if <exp1 is less than exp2.

■ Character: The comparison is based on the underlying ASCII

code. ASCII codes for alphabetic characters are ascending (e.g., the code for «A» is 65 and the code for «Z» is 90).

■ Date: Dates are compared according to the underlying date

value.

■ Logical: False (.F.) is less than true (.T.).

■ Memo: Treated the same as character.

■ Numeric: Compared based on magnitude.

■  These examples illustrate how the less than operator (<)
   behaves with different data types:

   // Character
   ? "Z" < "A"                 // Result: .F.
   ? "ZA" < "A"                // Result: .F.
   ? "A" < "AZ"                // Result: .T.

   // Date
   ? CToD("12/12/88") < ;
      CToD("12/11/88")         // Result: .F.

   // Logical
   ? .F. < .T.                 // Result: .T.


   // Numeric
   ? 2 < 1                     // Result: .F.
   ? 1 < 2                     // Result: .T.

The less than or equal (<= ) operator compares two values of the same data type and returns true (.T.) if exp1 is less than or equal to exp2.

■ Character: The comparison is based on the underlying ASCII

code. ASCII codes for alphabetic characters are ascending (e.g., the code for «A» is 65 and the code for «Z» is 90).

■ Date: Dates are compared according to the underlying date

value.

■ Logical: False (.F.) is less than true (.T.).

■ Memo: Treated the same as character.

■ Numeric: Compared based on magnitude.

■  These examples illustrate how the less than or equal operator
   (<=) behaves with different data types:

   // Character
   ? "Z" <= "A"               // Result: .F.
   ? "ZA" <= "A"              // Result: .F.
   ? "A" <= "AZ"              // Result: .T.

   // Date
   ? CToD("12/12/88") <= ;
      CToD("12/11/88")        // Result: .F.


   // Logical
   ? .F. <= .T.               // Result: .T.

   // Numeric
   ? 2 <= 1                  // Result: .F.
   ? 1 <= 2                  // Result: .T.
   ? 1 <= 1                  // Result: .T.

<exp1> <> <exp2>
<exp1> != <exp2>
<exp1> #  <exp2>

The not equal ( <>) operator compares two values of the same data type and returns true (.T.) if exp1 is not equal to exp2 according to the following rules:

■ Character: The comparison is based on the underlying ASCII

code and is the inverse of the equal operator (=). This means that the comparison is sensitive to the current EXACT SETting. See the examples below.

■ Date: Dates are compared according to the underlying date

value.

■ Logical: False (.F.) is not equal to true (.T.).

■ Memo: Treated the same as character.

■ NIL: All values compared to NIL other than NIL return true

(.T.).

■ Numeric: Compared based on magnitude.

■  These examples illustrate how the not equal operator (<>)
   behaves with different data types:

   // Character
   SET EXACT ON
   ? "123" <> "12345"         // Result: .T.
   ? "12345" <> "123"         // Result: .T.
   ? "123" <> ""              // Result: .T.
   ? "" <> "123"              // Result: .T.
   SET EXACT OFF
   ? "123" <> "12345"         // Result: .T.
   ? "12345" <> "123"         // Result: .F.
   ? "123" <> ""              // Result: .F.
   ? "" <> "123"              // Result: .T.

   // Date
   ? CToD("12/12/88") <> ;
      CToD("12/12/88")        // Result: .F.

   // Logical
   ? .T. <> .T.               // Result: .F.
   ? .T. <> .F.               // Result: .T.

   // NIL
   ? NIL <> NIL               // Result: .F.
   ? NIL <> 12                // Result: .T.
   ? NIL <> "hello"           // Result: .T.

   // Numeric
   ? 2 <> 1                   // Result: .T.
   ? 1 <> 1                   // Result: .F.

The simple assignment operator (=) assigns a value to a variable. It is identical in operation to the STORE command that initializes a single variable and must be specified as a program statement. The inline assignment operator (:=) is like the = operator except that you can specify it within expressions. If you specify the simple assign operator (=) within an expression, it is interpreted as the equality (=) operator.

Note: You cannot initialize a specific variable using the simple assign operator (=) in a declaration statement. Only the inline assign (:=) operator can be used for this purpose.

If the reference to idVar is ambiguous (i.e., not declared at compile time and not explicitly qualified with an alias), idVar is always assumed to be MEMVAR. At runtime, if no private or public variable exists with the specified name, a private variable is created. To assign a field variable with the = operator, you must declare the field variable name in a FIELD statement or refer to the field name prefaced by the FIELD-> alias or the name of the work area.

■  These examples are valid simple assignment statements:

   nValue = 25
   nNewValue = Sqrt(nValue) ** 5
   nOldValue = nValue

■  In this example, the two lines are equivalent:

   FIELD->CustAge = 20
   REPLACE CustAge WITH 20

<idVar>  += <cString>         (concatenation)
<idVar>  += <nNumber>         (addition)
<idVar>  -= <cString>         (concatenation)
<idVar>  -= <nNumber>         (subtraction)
<idVar>  -= <dDate>           (subtraction)
<idVar>  *= <nNumber>         (multiplication)
<idVar>  /= <nNumber>         (division)
<idVar>  %= <nNumber>         (modulus)
<idVar>  ^= <nNumber>         (exponentiation)

In addition to the simple and inline assignment operators (= and :=), there are a series of compound assignment operators that perform an operation then assign a value. They have the form:

idVar operator= exp

Each compound assignment expression is equivalent to the assignment expression:

idVar := ( idVar operator exp )

For each data type that supports an operator, the compound assignment operator performs the same operation before performing the assignment operation. The following table details all of the compound operators:

Compound Operators

Note: The exponentiation operator (**) does not have a corresponding compound assignment operator. The exponentiation compound assignment operator is ^=.

Since the compound assignment operators are based on the inline assignment operator (:=), the operation returns the result of its operation as the value of the expression. This means you can use these operators within expressions just like the inline assignment operator (:=).

■  These examples use the compound addition and concatenation
   assignment operator:

   // Character (concatenation)
   LOCAL cString := "Hello"
   ? cString += " there"           // Result: "Hello there"

   // Date (addition)
   LOCAL dDate := CToD("12/12/90")
   dDate += 12                     // Result: 12/24/90

   // Numeric (addition)
   LOCAL nValue := 10
   ? Sqrt(nValue += 15)            // Result:  5.00
   ? nValue                        // Result: 25.00

■  These examples use the compound subtraction and concatenation
   assignment operator:

   // Character (concatenation)
   LOCAL cString := "Hello   "
   ? cString -= "There"            // Result: HelloThere

   // Date (subtraction)
   LOCAL dDate := CToD("12/24/90")
   dDate -= 12                     // Result: 12/12/90

   // Numeric (subtraction)
   LOCAL nValue := 10
   ? newValue := (nValue -= 5) ** 2       // Result: 25
   ? nValue                               // Result:  5

■  This example uses the compound multiplication assignment
   operator:

   LOCAL nValue := 10
   ? newValue := (nValue *= 5) + 100      // Result: 150
   ? nValue                               // Result:  50

■  This example uses the compound division assignment operator:

   LOCAL nValue := 10
   ? newValue := (nValue /= 5) + 100      // Result: 102.00
   ? nValue                               // Result:   2.00

■  This example uses the compound modulus assignment operator:

LOCAL nValue := 10
   ? newValue := (nValue %= 4) * 100      // Result: 200.00

   ? nValue                               // Result:   2.00

■  This example uses the compound exponentiation assignment
   operator:

   LOCAL nValue := 10
   ? newValue := (nValue ^= 3) + 50       // Result: 1050.00
   ? nValue                               // Result: 1000.00

The equal operator (= ) compares two values of the same data type and returns true (.T.) if exp1 is equal to exp2 according to the following rules:

■ Character: The comparison is based on the underlying ASCII

code. ASCII codes for alphabetic characters are ascending (e.g., the code for «A» is 65 and the code for «Z» is 90).

When EXACT is OFF, two character strings are compared according to the following rules. assume two character strings, cLeft and cRight, where the expression to test is (cLeft = cRight):

— If cRight is null, returns true (.T.).

— If Len(cRight) is greater than Len(cLeft), returns false

(.F.).

— Compare all characters in cRight with cLeft. If all

characters in cRight equal cLeft, returns true (.T.); otherwise, returns false (.F.).

With EXACT ON, two strings must match exactly except for trailing blanks.

■ Date: Dates are compared according to the underlying date

value.

■ Logical: True (.T.) is equal to true (.T.) and false (.F.)

equal to false (.F.).

■ Memo: Treated the same as character.

■ NIL: True (.T.) if compared to a NIL value; false (.F.) if

compared to a value of any other data type.

■ Numeric: Compared based on magnitude.

■  These examples illustrate how the equal operator (=) behaves
   with different data types:

   // Character
   SET EXACT ON
   ? "123" = "123  "        // Result: .T.
   ? " 123" = "123"         // Result: .F.
   SET EXACT OFF
   ? "123" = "12345"        // Result: .F.
   ? "12345" = "123"        // Result: .T.
   ? "123" = ""             // Result: .T.
   ? "" = "123"             // Result: .F.

   // Date
   ? CToD("12/12/88") = ;
      CToD("12/12/88")      // Result: .T.

   // Logical
   ? .T. = .T.              // Result: .T.
   ? .F. = .T.              // Result: .F.

   // NIL
   ? NIL = NIL              // Result: .T.
   ? NIL = 12               // Result: .F.
   ? NIL = CToD("")         // Result: .F.

   // Numeric
   ? 2 = 1                  // Result: .F.
   ? 1 = 1                  // Result: .T.

The exactly equal operator (==) is a binary operator that compares two values of the same data type for exact equality depending on the data type. It returns true (.T.) if exp1 is equal to exp2 according to the following rules:

■ Array: Compares for identity. If exp1 and exp2 are

variable references to the same array, returns true (.T.); otherwise, returns false (.F.).

■ Character: Comparison is based on the underlying ASCII code.

ASCII codes for alphabetic characters are ascending (e.g., the code for «A» is 65 and the code for «Z» is 90). Unlike the relational equality operator (=) , true (.T.) is returned if exp1 and exp2 are exactly equal including trailing spaces; otherwise, the comparison returns false (.F.). SET EXACT has no effect.

■ Date: Dates are compared according to the underlying date

value; behaves the same as the relational equality operator (=).

■ Logical: True (.T.) is exactly equal to true (.T.), and false

(.F.) is exactly equal to false (.F.).

■ Memo: Treated the same as character.

■ NIL: True (.T.) if compared to a NIL value; false (.F.) if

compared to a value of any other data type.

■ Numeric: Compared based on magnitude; behaves the same as the

relational equality operator (=).

■ Object: Treated the same as array.

■  These examples illustrate how the == operator behaves with
   different data types:

   // Character
   ? "A" == "A"             // Result: .T.
   ? "Z" == "A"             // Result: .F.
   ? "A" == "A "            // Result: .F.
   ? "AA" == "A"            // Result: .F.

   // Array or object

   aOne := { 1, 2, 3 }
   aTwo := { 1, 2, 3 }
   aThree := aOne
   ? aOne == aTwo           // Result: .F.
   // values within the arrays are equal, but the arrays,
   // themselves, are separate and distinct
   ? aOne == aThree         // Result: .T.

The greater than (>) operator compares two values of the same data type and returns true (.T.) if exp1 is greater than exp2.

■ Character: The comparison is based on the underlying ASCII

code. ASCII codes for alphabetic characters are ascending (e.g., the code for «A» is 65 and the code for «Z» is 90).

■ Date: Dates are compared according to the underlying date

value.

■ Logical: True (.T.) is greater than false (.F.).

■ Memo: Treated the same as character.

■ Numeric: Compared based on magnitude.

■  These examples illustrate how the greater than operator (>)
   behaves with different data types:

   // Character
   ? "Z" > "A"             // Result: .T.
   ? "AZ" > "A"            // Result: .F.
   ? "A" > "AZ"            // Result: .F.

   // Date

   ? CToD("12/12/88") > ;
      CToD("12/11/88")     // Result: .T.

   // Logical
   ? .T. > .F.             // Result: .T.

   // Numeric
   ? 2 > 1                 // Result: .T.
   ? 1 > 2                 // Result: .F.

The greater than or equal to operator (>=) is a binary operator that compares two values of the same data type and returns true (.T.) if exp1 is greater than or equal to exp2.

■ Character: The comparison is based on the underlying ASCII

code. ASCII codes for alphabetic characters are ascending (e.g., the code for «A» is 65 and the code for «Z» is 90).

■ Date: Dates are compared according to the underlying date

value.

■ Logical: True (.T.) is greater than false (.F.).

■ Memo: Treated the same as character.

■ Numeric: Compared based on magnitude.

■  These examples illustrate how the greater than or equal
   operator (>=) behaves with different data types:

   // Character
   ? "Z" >= "A"             // Result: .T.

   ? "AZ" >= "A"            // Result: .T.
   ? "A" >= "AZ"            // Result: .F.

   // Date
   ? CToD("12/12/88") >= ;
      CToD("12/11/88")      // Result: .T.

   // Logical
   ? .T. >= .F.             // Result: .T.

   // Numeric
   ? 2 >= 1                 // Result: .T.
   ? 1 >= 2                 // Result: .F.
   ? 2 >= 2                 // Result: .T.

<nNumber1> - <nNumber2>             (subtraction)
<dDate1>   - <dDate2>               (subtraction)
<dDate>    - <nNumber>              (subtraction)
<cString1> - <cString2>             (concatenation)

The (-) operator performs different operations depending on the data types of the operands:

■ Unary negative sign (numeric): A numeric expression prefaced

with the minus (-) operator performs the equivalent of multiplying the operand by (-1), returning a negative numeric value.

■ Binary subtraction (numeric, date): If both operands are

numeric data type, nNumber2 is subtracted from nNumber1 and the result is returned as a numeric value. If both operands are date data type, dDate2 is subtracted from dDate1 and the result is returned as a numeric value representing the number of days between the two dates. If the left operand is date data type and the right operand numeric data type, the nNumber is subtracted as days from dDate and a date value is returned. If the order of operands is reversed, a runtime error occurs.

■ Concatenation (character, memo): If both operands are

character data type, cString2 is joined to cString1, returning a character string. Trailing blanks are trimmed from cString1 and joined to the end of the return string.

■  These examples illustrate the various forms of the - operator:

   // Binary subtraction (numeric)
   ? 1 - 1                           // Result: 0
   ? 1 - 0                           // Result: 1
   ? 0 - 1                           // Result: -1

   // Binary subtraction (date)

   ? CToD("12/12/88") - 12         // Result: 11/30/88
   ? 12 - CToD("12/12/88")         // Result: Runtime error

   // Concatenation (character)
   ? "Hi " - "There" + "*"         // Result: Hithere *

<idAlias>-><idField>
<idAlias>->(<exp>)
(<nWorkArea>)-><idField>
(<nWorkArea>)->(<exp>)
FIELD-><idVar>
MEMVAR-><idVar>

When used with an idAlias as the first operand, the alias operator

(->) accesses field information or evaluates an expression in the indicated work area. The alias operator implicitly SELECTs the idAlias before evaluating the idField or exp operand. When the evaluation is complete, the original work area is SELECTed again. An alias reference can be in an expression or on a line by itself:

? Customer->Name Customer->(UpdateTransaction())

Using the alias operator lets you:

■ Access information from unselected work areas within

expressions

■ Access environmental information from unselected work areas

■ Access information from unselected work areas in modes such as

REPORT and LABEL FORMs

■ Write more compact code

In addition to allowing expression and field evaluation in unselected work areas, the alias operator makes an explicit reference to a field or variable using either the FIELD or the MEMVAR keyword aliases. MEMVAR forces idVar to refer to a memory variable name, and FIELD forces it to reference a database field. These special alias identifiers allow you to avoid ambiguity when there are conflicts between field and memory variable names. Remember that a reference to a variable identifier not prefaced with an alias defaults to a field if there are both field and memory variables with the same name. To override this, use the (/V) option when compiling.

In addition to specifying the alias as an identifier, you can access the target work area using an expression that returns the work area number if the expression is enclosed by parentheses. This lets you use work area numbers as handles, which is useful for passing references to work areas without using macros, aliases, names, etc.

■  This example accesses database and work area information in an
   unselected work area:

   USE Customer NEW
   USE Invoices NEW
   ? Customer->CustName                  // Result: Bill Smith
   ? Customer->(RecNo())                 // Result: 1
   ? Customer->(Found())                 // Result: .F.
   ? Customer->(City + ", " + State + ;
      "  " + Zip)                        // Result: ShadowVille,
                                         //         CA  90415

■  This example uses a user-defined function (MySeek()) as an
   operand of the alias operator for a common operation that normally
   requires many more statements:

   IF Invoices->(MySeek(CustNum))
      <process customer>...
   ELSE
      <process no find>...
   ENDIF
   RETURN

   FUNCTION MySeek( cSearch )
      SEEK cSearch
   RETURN (Found())

   Note:  This example is just an illustration of the alias operator
   with a user-defined function.  CA-Clipper's dbSeek() could be used
   instead of MySeek().

■  This example explicitly references field and memory variables
   with the same name:

   USE Customer NEW
   MEMVAR->CustName = "Bill Smith"      // Create a memvar
                                        // CustName
   LOCATE FOR MEMVAR->CustName = FIELD->CustName

■  This example uses an expression as a work area handle to
   create a work area-independent database operation:

   cTable1 := "C:Myfile.dbf"
   cTable2 := "D:Myfile.dbf"
   USE (cTable1) NEW
   hArea1 = Select()
   USE (cTable2) NEW
   hArea2 = Select()
   DoStuff( hArea1, hArea2 )

   FUNCTION DoStuff( hArea1, hArea2 )
      LOCAL nCount, nSave
      nSave := Select()
      SELECT (hArea1)
      FOR nCount := 1 TO FCount()
         FieldPut( nCount, ( hArea2 )-> ;
            ( FieldGet( nCount )))
      NEXT
      SELECT (nSave)
      RETURN NIL

--<idVar>       (prefix decrement)
<idVar>--       (postfix decrement)

The decrement operator (—) decreases the value of its operand by one. This operator subtracts one from the value of idVar and assigns the new value to idVar.

The — operator can appear before or after idVar. Specifying the operator before idVar decrements and assigns the value before the value is used. This is called prefix notation, and it is the most common usage. Specifying the operator after idVar decrements and assigns the value after it is used. This is postfix notation. Stated differently, postfix notation delays the assignment portion of the operation until the rest of the expression is evaluated, and prefix notation gives the assignment precedence over all other operations in the expression.

If the reference to idVar is ambiguous (i.e., not declared at compile time and not explicitly qualified with an alias), idVar is always assumed to be MEMVAR. You can assign field variables by declaring the field variable name in a FIELD statement or by referring to the field name prefaced by the FIELD-> alias or by the name of the work area.

■  In this example of the postfix decrement operator the
   assignment takes place before the original variable is decremented,
   thus the two values are not the same when queried:

   nValue := 1
   nNewValue := nValue--
   ? nNewValue                  // Result:   1
   ? nValue                     // Result:   0

■  In this example, the prefix decrement operator decreases the
   first operand of the multiplication by one, making its value 9.
   Then, the assignment of this new value to the nValue variable takes
   place before the rest of the expression is evaluated.  Thus, the new
   value is used to perform the multiplication operation, and the result
   of 9 * 9 is 81.

   nValue := 10
   ? --nValue * nValue          // Result:  81
   ? nValue                     // Result:   9

<object>:<message>[(<argument list>)]

Each class defines a set of operations that can be performed on objects of that class. Perform these operations by sending a message to the object using the send operator (:).

When a message is sent to an object, the system examines the message. If the object is of a class that defines an operation for that message, the system automatically invokes a method to perform the operation on the specified object. If the class does not define a method for the specified message, a runtime error occurs.

Executing a message send produces a return value, much like a function call. The return value varies depending on the operation performed.

■  In this example, myBrowse is the name of a variable that
   contains a TBrowse object reference.  pageUp() is a method that
   specifies the operation to be performed.  The available operations
   and corresponding methods vary depending on the class of the object.
   The Error, Get, TBColumn, and TBrowse classes are documented in this
   chapter.

   myBrowse:pageUp()

■  This example forces the checkbox state to true (.T.):

   myCheck : Select (.T.)

The inline assignment operator (:=) assigns values of any data type to variables of any storage class. The operator evaluates exp, assigns the resulting value to idVar, and returns the resulting value as the return value of the operation. This latter behavior permits multiple assignments such as idVar1 := idVar2 := value. Unlike the simple assign operator (=), the inline assignment operator (:=) can be used anywhere an expression or constant is allowed, including variable declaration statements. With a variable declaration statement, assignment initializes a variable. Note, however, you cannot declare an array and initialize elements within the same program statement.

If the reference to idVar is ambiguous (i.e., not declared at compile time and not explicitly qualified with an alias), idVar is always assumed to be MEMVAR. At runtime, if no private or public variable exists with the specified name, a private variable is created. You can assign field variables with the := operator by declaring the field variable name in a FIELD statement or referring to the field name prefaced by the FIELD-> alias or the name of the work area.

■  Several examples of inline assignment follow:

   LOCAL nValue := 10
   //
   IF (dDate := (Date() - 1000)) = CToD("12/20/79")
   //
   ? Sqrt(nValue := (nValue ** 2))
   //
   cTransNo := cSortNo := (CustId + DToC(Date()))

■  This last example performs multiple assignments using the
   inline assignment operator as you would with the STORE command.  When
   := is used in this way, the assignments are executed from right to
   left.  This feature is particularly useful when you need to store the
   same value to many different fields, possibly in different database
   files.

   CustFile->CustId := TransFile-> ;
      TransNo := (CustId + DToC(Date())

exp list is a list of values to display and can be any combination of data types, including memo.

If you specify no argument and use the ? command, a carriage return/linefeed is sent to the console. If you use the ?? command without arguments, nothing happens.

? and ?? are console commands that display the results of one or more expressions, separated by a space, to the console. These commands are also command synonyms for the QOut() and QQOut() functions, respectively.

Although functionally similar, ? and ?? differ slightly. ? sends a carriage return/linefeed to the console before displaying the results of the expression list. ?? displays output at the current screen cursor or printhead position. This lets you use successive ?? commands to display output to the same line.

A ? or ?? command locates the cursor or printhead one position to the right of the last character displayed. If SET PRINTER is OFF, Row() and Col() are updated to reflect the new cursor position. If SET PRINTER is ON, PRow() and PCol() are updated with the new printhead position.

If output from a ? or ?? command reaches the edge of the screen as reported by MaxCol(), it wraps to the next line. If the output reaches the bottom of the screen as reported by MaxRow(), the screen scrolls up one line.

You can echo output from the ? or ?? commands to the printer by specifying a SET PRINTER ON command before beginning output. You can echo output from both of these commands to a text file using SET ALTERNATE TO xcFile to create the file, and SET ALTERNATE ON to begin echoing to the file. Like other console commands, SET CONSOLE OFF suppresses the display to the screen without affecting output to the printer or text file.

To format any expression specified, use Transform() or a user-defined function. If you need to pad a variable length value for column alignment, use any of the Pad() functions to left-justify, right- justify, or center the value. See the examples below.

■  This example prints a record from a database file using ? and
   ?? commands with PadR() to ensure column alignment:

   LOCAL nPage := 0, nLine := 99
   USE Salesman INDEX Salesman NEW
   SET PRINTER ON
   SET CONSOLE OFF
   DO WHILE !Eof()
      IF nLine > 55
         IF nPage != 0
            EJECT
         ENDIF
         ? PadR("Page", LTrim(Str(nPage++)), 72)
         ?? DToC(Date())
         ?
         ?
         ? PadC("Sales Listing", 79)
         ?
         nLine := 5
      ENDIF
      ? Name, Address, PadR(RTrim(City) + "," ;
            + State, 20), ZipCode
      nLine++
      SKIP
   ENDDO
   SET CONSOLE ON
   SET PRINTER OFF
   CLOSE Salesman

The division operator (/) returns a numeric value from the division of nNumber1 by nNumber2.

Note: Dividing nNumber1 with zero value for nNumber2 results in a runtime error.

■  This example shows division results to 16 decimal places,
   using different operands:

   SET DECIMALS TO 16
   ?  3 /  0            // Result: Runtime error
   ?  3 / -2            // Result: -1.500000000
   ? -3 /  2            // Result: -1.500000000
   ? -3 /  0            // Result: Runtime error
   ? -1 / -3            // Result: +0.333333333
   ? -2 /  3            // Result: -0.666666667
   ?  2 / -3            // Result: -0.666666667
   ?  1 / -3            // Result: -0.333333333

<lCondition1> .AND. <lCondition2>

The .AND. operator is a binary logical operator that executes a logical AND operation using the following modified Boolean rules:

■ Returns true (.T.) if both lCondition1 and lCondition2

evaluate to true (.T.)

■ Returns false (.F.) if either lCondition1 and lCondition2

evaluate to false (.F.)

Warning! In a departure from Summer ’87 and other dialect behavior, CA-Clipper shortcuts the evaluation of .AND. operands. This means that lCondition1 and lCondition2 are both evaluated only when lCondition1 evaluates to TRUE (.T.). If lCondition1 evaluates to FALSE (.F.), the .AND. operation is FALSE (.F.) and lCondition2 is therefore not evaluated.

For backward compatibility, shortcutting can be suppressed by compiling with the /Z option.

■  This example shows .AND. results using different operands:

   ? .T. .AND. .T.            // Result: .T.
   ? .T. .AND. .F.            // Result: .F.
   ? .F. .AND. .T.            // Result: .F.   (shortcut)
   ? .F. .AND. .F.            // Result: .F.   (shortcut)

! <lCondition>
.NOT. <lCondition>

■  This example shows .NOT. results using different operands:

   ? ! (.T.)               // Result: .F.
   ? ! 1 > 2               // Result: .T.
   ? .NOT. 1 > 2           // Result: .T.

<lCondition1> .OR. <lCondition2>

The .OR. operator is a binary logical operator that executes a logical OR operation using the following modified Boolean rules:

■ Returns true (.T.) if either lCondition1 or lCondition2

evaluates to true (.T.)

■ Returns false (.F.) if both lCondition1 and lCondition2

evaluates to false (.F.)

Warning! In a departure from the Summer ’87 and other dialect behavior, CA-Clipper shortcuts the evaluation of .OR. operands. This means that lCondition1 and lCondition2 are both evaluated only when lCondition1 evaluates to false (.F.). If lCondition1 evaluates to true (.T.), the .OR. operation is true (.T.) and lCondition2 is, therefore, not evaluated. For backward compatibility, shortcutting can be suppressed by compiling with the /Z option.

■  This example shows .OR. results using different operands:

   ? .T. .OR. .T.            // Result: .T.   (shortcut)
   ? .T. .OR. .F.            // Result: .T.   (shortcut)
   ? .F. .OR. .T.            // Result: .T.
   ? .F. .OR. .F.            // Result: .F.

Parentheses (()) in expressions are used to group certain operations for readability or to force a particular evaluation order. Parentheses also identify a function call.

When specifying the grouping operator, the item that falls within the parentheses must be a valid expression. Subexpressions may be further grouped.

For function calls, a valid function name must precede the left parenthesis, and the function arguments, if any, must be contained within the parentheses.

■  This example changes the default order of expression
   evaluation:

   ? 5 * (10 + 6) / 2         // Result: 40

■  The next example shows a function call:

   x := Sqrt(100)

<aArray>[<nSubscript>, ... ]
<aArray>[<nSubscript1>][<nSubscript2>] ...

■  This example accesses each element in a two-dimensional array
   of known dimensions:

   LOCAL i, j
   FOR i := 1 TO 5
      FOR j := 1 TO 10
         ? aOne[i, j]
      NEXT
   NEXT

■  These examples specify an <aArray> expression:

   LOCAL aArray := { 1, 2, 3, 4, 5 }
   //
   ? ArrayFunc()[2]                     // Result: 2
   ? { {1, 2}, {3, 4} }[1][2]           // Result: 2
   ? aArray[5]                          // Result: 5

   FUNCTION ArrayFunc
      STATIC aArray := { 1, 2 }
      RETURN aArray

■  This example queries and assigns a static array encapsulated
   within a function definition:

   ? ArrayFunc()[1]                     // Result: 1
   ArrayFunc()[1] := 10
   ? ArrayFunc()[1]                     // Result: 10

   FUNCTION ArrayFunc
      STATIC aArray := { 1, 2 }
      RETURN aArray

{ <exp list> }                 (literal array)
{ |<param list>| <exp list> }  (code block definition)

■  This example uses literal arrays in declaration statements to
   create a variable and initialize it with an array reference:

   LOCAL aPerson := { "Name", "Address", Date() }
   STATIC aNumList := { 1, 2, 3, 4, 5, 6, 7, 8 }

■  This example creates a multidimensional literal array:

   aMulti := { {1, 2, 3}, {"A", "B", "C"} }

■  This example uses curly braces to formulate a simple code
   block with a single parameter:

   LOCAL bSayBlock
   bSayBlock := { |x| QOut(x) }
   Eval(bSayBlock, 10)               // Result: 10

The pass-by-reference operator (@) passes variables by reference to functions or procedures invoked with function-calling syntax. It is a unary prefix operator whose operand may be any variable name.

Passing a variable by reference means that a reference to the value of the argument is passed instead of a copy of the value. The receiving parameter then refers to the same location in memory as the argument. If the called routine changes the value of the receiving parameter, it also changes the argument passed from the calling routine.

Passing a variable by value means that the argument is evaluated and its value is copied to the receiving parameter. Changes to a receiving parameter are local to the called routine and lost when the routine terminates. The default method of passing arguments is by value for all data types including references to arrays and objects.

■  This example demonstrates the difference between passing a
   user-defined function argument by reference and by value:

   LOCAL nNum := 1                     // Initial values

   LOCAL aArr := { "a", "b", "c" }
   //
   CLS
   // Print initial values
   ? ValType(nNum), nNum
   ? ValType(aArr), aArr[1], aArr[2], aArr[3]
   //
   Udf1(nNum)                          // Pass by value (default)
   ? ValType(nNum), nNum               // Result:  N, 1
   //
   Udf1(aArr[1])                       // Pass by value (default)
   ? ValType(aArr), aArr[1],;
         aArr[2], aArr[3]              // Result:  A, "a" "b" "c"
   //
   Udf2(aArr)                          // Pass a reference to
   ? ValType(aArr), aArr[1],;          // the array (default)
         aArr[2], aArr[3]              // A, "Oi!" "b" "c"
   //
   Udf1(@nNum)                         // Force pass by reference
   ? ValType(nNum), nNum               // Result:  N, 1000
   //
   Udf3(@aArr)                         // Pass array by reference
   ? ValType(aArr)                     // Result:  N
   //
   RETURN NIL


   FUNCTION Udf1(nParam)               // Receive as a local
   ? nParam                            // parameter
   nParam := 1000
   ? nParam
   RETURN NIL
   //
   FUNCTION Udf2( aParam )             // Receive as a local
   ? ValType(aParam), aParam[1]        // parameter
   aParam[1] := "Oi!"
   ? aParam[1]
   RETURN NIL
   //
   FUNCTION Udf3(aParam)               // Receive as a local
   ? ValType(aParam), aParam[1]        // parameter
   aParam := 1000
   ? aParam
   RETURN NIL

@ <nTop>, <nLeft>, <nBottom>, <nRight>
   BOX <cBoxString> [COLOR <cColorString>]

nTop, nLeft, nBottom, nRight define the coordinates of the box. @...BOX 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.

BOX cBoxString defines a string of eight border characters and a fill character. If cBoxString is specified as a single character, that character draws the whole box.

COLOR cColorString defines the display color of the drawn box. 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.

@...BOX draws a box on the screen using configurable border and fill characters. @...BOX draws the box using cBoxString 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 @...BOX 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.

■  These examples draw two boxes using box manifest constants
   defined in the supplied header file, box.ch.  The first example draws
   a box using the specified characters for the border, but leaves all
   other areas of the screen intact.  The second example draws the same
   box filling the box region with space characters.

   #include "Box.ch"
   // Draw a box with a double-line top with a
   // single-line side
   @ 1, 1, 22, 79 BOX B_DOUBLE_SINGLE
   // Draw the same box filling the box region with
   // spaces
   @ 1, 1, 22, 79 BOX B_DOUBLE_SINGLE + Space(1)

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

nTop and nLeft define the upper-left corner coordinate.

TO nBottom, nRight defines the lower-right corner coordinates of the screen region to CLEAR. If the TO clause is not specified, these coordinates default to MaxRow() and MaxCol().

■  This example erases the screen from 10, 10 to 20, 40, painting
   the region blue and then displaying a bright cyan box on blue:

   SetColor("BG+/B")
   @ 10, 10 CLEAR TO 20, 40
   @ 10, 10 TO 20, 40

@ <nRow>, <nCol>
   [SAY <exp>
      [PICTURE <cSayPicture>]
      [COLOR <cColorString>]]
   GET <idVar>
      [PICTURE <cGetPicture>]
      [COLOR <cColorString>]
      [CAPTION<cCaption>]
      [MESSAGE <cMessage>]
      [WHEN <lPreExpression>]
      [RANGE* <dnLower>, <dnUpper>] |
      [VALID <lPostExpression>]
      [SEND <msg>]
      [GUISEND <guimsg>]

nRow and nCol specify the row and column coordinates for the operation. If the SAY clause is present, nRow and nCol specify the coordinates for the SAY, and the GET is displayed to the right of the SAY output. If the SAY clause is not present, nRow and nCol directly specify the coordinates for the GET. In either case, output which extends beyond the visible extent of the display is clipped and does not appear.

SAY exp displays the value of exp at the specified coordinates. If you specify the PICTURE cSayPicture clause, exp is formatted according to the rules of SAY pictures.

GET idVar specifies the name of the variable associated with the GET. idVar may be of any storage class (if the storage class is ambiguous, FIELD is assumed). If idVar contains an array value, you must supply one or more subscripts. The current value of idVar is displayed at the GET coordinates. The value must be character, date, numeric, or logical type. Array, NIL, code block, and null string values are not permitted.

PICTURE cGetPicture specifies the display format and editing rules for the GET.

COLOR cColorString defines the color settings for the current Get object. cColorString is a character expression containing one or more color settings. You must specify literal color settings enclosed in quote marks.

If you specify two color settings, the first determines the unselected color (the display color for the Get object) and the second determines the selected color (the color when the Get object has focus). If you only specify one color, it determines both the unselected and selected colors for the Get object.

On a combined @...SAY...GET command, two COLOR clauses are required to specify colors for both the SAY and the GET: one for the SAY, and one for the GET.

CAPTION cCaption specifies a character string that concisely describes the GET on the screen. Caption differs from the SAY argument in two ways. The first is that the caption is displayed each time the GET is shown on the screen. The other difference is that the caption, along with its screen position, is maintained within the Get object. This allows the GET to receive input when the mouse’s left button is clicked and its cursor is on the caption. By default, the caption appears to the right of the GET. Use the Get object’s capRow or capCol variable to change the screen position of the caption. Note that if the SAY clause is used, the CAPTION clause is ignored.

When present, the & character specifies that the character immediately following it in the caption is the GET‘s accelerator key. The accelerator key provides a quick and convenient mechanism for the user to move input focus from one data input control to the GET. The user performs the selection by pressing the Alt key in combination with an accelerator key. The case of an accelerator key is ignored.

MESSAGE cMessage specifies a character string that is displayed on the Get system’s status bar line when the GET has input focus. Typically, it describes the anticipated contents or user response of the GET. Refer to the SET MESSAGE command for details pertaining to the Get system’s status bar.

WHEN lPreExpression specifies an expression that must be satisfied before the cursor can enter the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

RANGE* dnLower, dnUpper specifies a range of allowable values for input to the GET. During a READ command, if you enter a new GET value that does not fall within the specified range, the cursor cannot leave the GET.

VALID lPostExpression specifies an expression that must be satisfied before the cursor can leave the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

SEND msg sends the specified message to the Get object. msg is sent before the GET is displayed. Any message can be sent, including method calls and instance variable assignments. Method calls must include parentheses even if no arguments are passed.

GUISEND guimsg can be used to send a message (such as the Display() method) to a GUI object. The GUI objects available in CA-Clipper are check boxes, list boxes, push buttons, and radio button groups. To send a message to a non-GUI object, such as standard GETs and TBrowses, use the SEND clause.

The @...GET command creates a new Get object, displays its value, and adds it to the array referred to by the variable GetList. If no variable called GetList has been declared or created in the current procedure, and no PRIVATE variable called GetList exists from a previous procedure, the system uses the predefined PUBLIC variable GetList. A subsequent READ command activates the GETs contained in the GetList array and allows the user to edit their contents.

Each Get object has an associated variable, idVar. The variable may be of any storage class, including a database field, private, public, local, or static variable. If idVar is followed by one or more subscripts, the specified array element is associated with the GET. When the Get object is created, the idVar name is stored in the Get object, along with a code block which allows the value of idVar to be retrieved or assigned during the READ.

The READ command performs a full-screen edit of the GETs in the GetList array. As the user moves the cursor into each GET, the value of the associated idVar is retrieved by evaluating the code block saved in the Get object. The value is converted to textual form and placed in a buffer within the Get object. This buffer is displayed on the screen, and the user is allowed to edit the text from the keyboard. When the user moves the cursor out of the GET, the updated buffer is converted back to the appropriate data type and assigned to idVar.

Automatic formatting and validation: During a READ, some formatting and edit validation is automatically performed for numeric, date, and logical values. As the user is typing, an automatic data type test is performed on each key pressed, preventing the user from entering an invalid character.

Prevalidation: The WHEN clause specifies a condition which must be satisfied before the cursor can enter the GET. During a READ, lPreExpression is evaluated whenever the user attempts to move the cursor into the GET. If it evaluates to true (.T.), the cursor can enter; otherwise, the GET is skipped.

Postvalidation: You may perform postvalidation using either the VALID or RANGE* clauses. VALID specifies a condition which must be satisfied before the cursor can leave the GET. During a READ, lPostExpression is evaluated whenever the user attempts to move the cursor out of the GET. If it evaluates to true (.T.), the cursor can leave; otherwise, the cursor remains in the GET. RANGE* specifies a range of acceptable values for numeric or date values. If the value entered by the user is not within the specified range, the cursor cannot leave the GET.

Note: You may specify either a VALID or RANGE clause, but not both.

PICTURE: When you specify the PICTURE clause for a GET, the character string specified by cGetPicture controls formatting and edit validation. The picture string controls the display format like a SAY picture. It also controls the way the user can edit the buffer. A picture string consists of two distinct parts, a function string and a template string, either or both of which may be present.

■ Function string: A PICTURE function string specifies

formatting or validation rules which apply to the GET‘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 the following table). The function string must be the first element of a PICTURE clause and cannot 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.

GET PICTURE Format Functions

■ Template string: A PICTURE template string specifies

formatting or validation rules on a character by character basis. The template string consists of a series of characters, some of which have special meanings (see the following table). Each position in the template string corresponds to a position in the displayed GET value. Characters in the template string that do not have assigned meanings are copied verbatim into the displayed GET value. If you use the @R picture function, these characters are inserted between characters of the display value, and are automatically removed when the display value is reassigned to idVar; otherwise, they overwrite the corresponding characters of the display value and also affect the value assigned to idVar. You may specify a template string alone or with a function string. If you use both, the function string must precede the template string, and the two must be separated by a single space.

GET PICTURE Template Symbols

SCOREBOARD: If a new value is rejected because it fails the RANGE* test or because it is a malformed date value, a message appears on the screen. The message displays in the SCOREBOARD area, which you can enable or disable using the SET SCOREBOARD command.

Exit with Esc: If the user exits a GET by pressing Esc, the GET variable is restored to the value it had on entry to the GET, and the READ is terminated. No postvalidation is performed. You can enable or suppress this behavior with the SET ESCAPE command.

SET KEY procedures: The SET KEY command lets you specify a procedure to be executed whenever a specific key is pressed during a READ. After a SET KEY procedure terminates, the GET is reactivated with the cursor restored to its previous position.

Lifetime of a Get object: Get objects, like arrays, exist as long as there are active references to them somewhere in the current program. Normally, only the array in the GetList variable maintains a reference to the Get object; the GET is released when GetList is released or reassigned. The CLEAR and CLEAR GETS commands assign an empty array to GetList, as does the READ command unless you specify the SAVE clause.

Assignment: Each GET is associated with a variable, idVar, in the @...GET command. At various times during the editing process, idVar may be assigned the current value of the Get object’s buffer. This occurs in the following instances:

■ After the user presses an exit key and before the validation

expression is executed

■ After the user presses a SET KEY

Also, the current Get object’s buffer is refreshed from idVar and redisplayed at various intervals:

■ After a SET KEY procedure terminates

■ After a WHEN expression is evaluated

■ After a VALID expression is evaluated

This lets you explicitly assign idVar within any of these operations. See the note below for more information.

GET coordinates and display: When you create a Get object using the @...GET command, the row and column coordinates at which the GET is initially displayed are stored in the Get object. When the @...GET command executes, the new GET displays at nRow and nCol, unless you specify the SAY clause which positions the GET so there is one display column between the last character of the SAY output and the first character of the GET (or of the DELIMITERS, see below).

If SET DELIMITERS is ON when the @...GET command executes, the current DELIMITER characters display on either side of the initial GET display, and the column coordinate of the GET is adjusted accordingly. Note that the delimiters are not attributes of the Get object, but simply display as the SAY clause does.

If INTENSITY is ON, GETs initially display in the current unselected color (or the enhanced color, if no unselected color has been specified). During a READ, the active GET displays in the enhanced color, while the remaining GETs display in the unselected color. With INTENSITY OFF, all GETs display in the standard color.

When a GET displays, the width of the displayed value is determined by the length of the value in idVar or, if you specify the PICTURE clause, by the number of positions in cGetPicture. If you specify the @S function as a part of cGetPicture, the @S argument controls the width of the displayed value.

■ WHEN and VALID: The expressions specified in the WHEN and

VALID clauses may be of arbitrary complexity and may include calls to user-defined functions. This is useful for attaching automatic actions to the activation or deactivation of a GET.

■ Assigning idVar: Because of the automatic refresh and

display properties of a Get object while it is being READ, you can make an explicit assignment to the Get object’s idVar within a WHEN or VALID expression. You can directly assign the variable by name in the validation expression or, for private, public, local, or static variables, by passing a reference to idVar to a function; the function can then assign idVar by assigning the corresponding formal parameter. If idVar is a field, it is globally visible and can be assigned by name in a function called by the validation expression.

When including a GET in a called function, do not include an idVar with the same name as a field idVar. Field references have precedence over public variables so the public idVar will be ignored.

■ GET specific help: You can use a SET KEY procedure to display

help text associated with a Get object. Within the SET KEY procedure, use the ReadVar() function to determine the idVar associated with the current Get object. Use this information to display the appropriate help text. Remember that when a CA-Clipper- compiled program loads, the F1 KEY is automatically SET TO a procedure or user-defined function named Help.

■ SET DEVICE TO PRINTER: SET DEVICE TO PRINTER does not direct

display of a Get object under the @...GET command to the printer or file.

■  This  example uses the VALID clause to validate input into a
   GET:

   LOCAL nNumber := 0
   @ 10, 10 SAY "Enter a number:" ;
      GET nNumber VALID nNumber > 0

■  This example demonstrates passing a code block with the VALID
   clause.  The parameter oGet is the current Get object.  Udf() changes
   the value of the GET:

   LOCAL GetList := {}, cVar := Space(10)
   CLS
   @ 10, 10 GET cVar  VALID { |oGet| Udf1( oGet ) }
   READ
   .
   .
   .
   * Udf( <oGet> ) --> .T.

   FUNCTION Udf1( oGet )

   IF "test" $ oGet:BUFFER          // Compare buffer contents
   oGet:varPut( "new value " )      // Change contents
   ENDIF

   RETURN .T.

■  This example uses the WHEN clause to prohibit entry into GETs
   based on the value of another GET.  In this example, entering Y in the
   Insured field indicates the client has insurance and the user is
   allowed to enter insurance information.  If the client does not have
   insurance, the cursor moves to the Accident field:

   @ 10, 10 GET Insured PICTURE "Y"
   @ 11, 10 GET InsNumber WHEN Insured
   @ 12, 10 GET InsCompany WHEN Insured
   @ 13, 10 GET Accident PICTURE "Y"
   READ

■  This is an example of a GET in a secondary work area:

   USE Invoice NEW
   APPEND BLANK
   USE Inventory NEW
   @ 1, 1 GET Invoice->CustNo
   READ

■  This example uses the @K function to suggest a default input
   value, but deletes it if the first key pressed is not a cursor key or
   Return:

   LOCAL cFile := "Accounts"
   @ 1, 1 SAY "Enter file" GET cFile PICTURE "@K"
   READ

■  This is an example of a nested READ using a GetList and
   lexical scoping:

   #include "inkey.ch"
   //
   // Local to this function only
   LOCAL GetList := {}
   LOCAL cName   := Space( 10 )
   //
   CLS
   SetKey( K_F2, { || MiscInfo() } )   // Hot key to special READ
   //
   // Get object added to getlist
   // works on local getlist
   @ 10, 10 SAY "Name" GET cName
   READ
   //
   RETURN NIL

   /***
   *  MiscInfo() ---> NIL
   */FUNCTION MiscInfo()
   //
   LOCAL GetList    := {}               // Local to this
   LOCAL cExtraInfo := Space( 30 )      // function only
   //
   // Get object added to getlist
   // works on local getlist
   @ 12, 10 SAY "Note: " GET cExtraInfo
   READ
   //
   RETURN NIL

@ <nRow>, <nCol>
   GET <lVar>
   CHECKBOX
      [CAPTION<cCaption>]
      [MESSAGE <cMessage>]
      [WHEN <lPreExpression>]
      [VALID <lPostExpression>]
      [COLOR <cColorString>]
      [FOCUS <fblock>
      [STATE <bBlock>]
      [STYLE <cStyle>]
      [SEND <msg>]
      [GUISEND <guimsg>]
      [BITMAPS <aBitmaps>]

nRow and nCol specify the row and column coordinates for the check box and its caption. Output which extends beyond the visible extent of the display is clipped and does not appear.

GET lVar specifies the name of the variable associated with the GET. lVar must contain a logical value. A value of true (.T.) indicates that the check box is checked; otherwise, a value of false (.F.) indicates that it is not checked.

CAPTION cCaption specifies a character string that concisely describes the GET on the screen. Caption differs from the SAY argument in two ways. The first is that the caption is displayed each time the GET is shown on the screen. The other difference is that the caption, along with its screen position, is maintained within the Get object. This allows the GET to receive input when the mouse’s left button is clicked and its cursor is on the caption. By default, the caption appears to the left of the GET. Use the Get object’s capRow or capCol variable to change the screen position of the caption.

When present, the & character specifies that the character immediately following it in the caption is the check box’s accelerator key. The accelerator key provides a quick and convenient mechanism for the user to move input focus from one data input control to the check box. The user performs the selection by pressing the Alt key in combination with an accelerator key. The case of an accelerator key is ignored.

MESSAGE cMessage specifies a character string that is displayed on the Get system’s status bar line when the GET has input focus. Typically, it describes the anticipated contents or user response of the GET. Refer to the READ command for details pertaining to the Get system’s status bar.

WHEN lPreExpression specifies an expression that must be satisfied before the cursor can enter the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

VALID lPostExpression specifies an expression that must be satisfied before the cursor can leave the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

COLOR cColorString defines the color settings for the check box. cColorString is a character expression containing exactly four color settings.

CheckBox Color Attributes

Note: In graphic mode, colorSpec positions 1 and 2 have no affect and are ignored.

FOCUS fblock specifies a code block that is evaluated each time the check box receives focus. The code block takes no implicit arguments. Use the CheckBox:hasFocus instance variable to determine if the check box has focus.

STATE bBlock specifies a code block that is evaluated each time the check box’s state changes. The code block takes no implicit arguments. Use the CheckBox:buffer instance variable to determine if the check box is being checked or unchecked. A value of true (.T.) indicates that it is being checked; otherwise, a value of false (.F.) indicates that it is being unchecked.

STYLE cStyle specifies a character string that indicates the check box’s delimiter characters. The string must contain four characters. The first is the left delimiter. Its default value is the left square bracket ([) character. The second is the checked indicator. Its default value is the square root

() character. The third is the unchecked indicator. Its default is

the space character (» «). The fourth character is the right delimiter. Its default value is the right square bracket (]) character.

Note: The style clause is ignored in graphic mode.

SEND msg sends the specified message to the Get object. msg is sent before the GET is displayed. Any message can be sent, including method calls and instance variable assignments. Method calls must include parentheses even if no arguments are passed.

GUISEND guimsg can be used to send a message (such as the Display() method) to a GUI object. The GUI objects available in CA-Clipper are check boxes, list boxes, push buttons, and radio button groups. To send a message to a non-GUI object, such as standard GETs and TBrowses, use the SEND clause.

BITMAPS aBitmaps contains an array of exactly two elements. The first element of this array is the file name of the bitmap to be displayed when the check box is selected. The second element of this array is the file name of the bitmap to be displayed when the check box is not selected.

Drive and directory names are not allowed; the file name extension is required. A bitmap file can be stored as a file on disk or in a bitmap library. If stored as a file, the file must reside in the same directory as the application. If stored in a bitmap library, the library must reside in the same directory as the application and it also must have the same name as the application with a .bml extension.

CA-Clipper will search for the file name first and, if it is not found, search in the bitmap library second. If no file is found either on disk or in the library, no bitmap will be displayed.

This argument only affects applications running in graphic mode and is ignored in text mode.

■  This example demonstrates how to add a check box to a data entry screen:

   @ 5, 20 GET lReadOnly CHECKBOX

■  This example demonstrates a check box that has a caption and a
   message:

   @ 5, 20 GET lReadOnly CHECKBOX ;
           CAPTION "&Read Only" ;
           MESSAGE "Check to open file for reading only"

■  This example demonstrates a check box that uses the X
   character as the checked character instead of the square root
   character.

   @ 5, 20 GET lReadOnly CHECKBOX ;
           CAPTION "&Read Only" ;
           MESSAGE "Check to open file for reading only" ;
           STYLE "[X ]"

@ <nTop>, <nLeft>, <nBottom>, <nRight>
   GET <nVar|cVar>
   LISTBOX <aList>
      [CAPTION<cCaption>]
      [MESSAGE <cMessage>]
      [WHEN <lPreExpression>]
      [VALID <lPostExpression>]
      [COLOR <cColorString>]
      [FOCUS <fblock>]
      [STATE <bBlock>]
      [DROPDOWN]
      [SCROLLBAR]
      [SEND <msg>]
      [GUISEND <guimsg>]
      [BITMAP <cBitmap>]

nTop, nLeft, nBottom and nRight specify the screen position for the list box and its caption. Output which extends beyond the visible extent of the display is clipped and does not appear.

GET nVar|cVar specifies the name of the variable associated with the GET. Its value indicates which item (if any) in the list is selected. A numeric value refers to the position in the list of the selected item. A value of 0 indicates no selected item. A character string value refers to the data or text contained within the selected item. A character string that does not refer to any item in the list indicates no selected item.

LISTBOX aList specifies an array that contains the items in the list. The array may be either a single- or two-dimensional array. Use a single-dimension array when the data being displayed is the same as the data being saved; otherwise, use a two-dimensional array. In this case, the data in the first element of each subarray is displayed and the data in the second element is used for determining which item is selected.

CAPTION cCaption specifies a character string that concisely describes the GET on the screen. Caption differs from the SAY argument in two ways. The first is that the caption is displayed each time the GET is shown on the screen. The other difference is that the caption, along with its screen position, is maintained within the Get object. This allows the GET to receive input when the mouse’s left button is clicked and its cursor is on the caption. By default, the caption appears to the left of the GET. Use the Get object’s capRow or capCol variable to change the screen position of the caption.

When present, the & character specifies that the character immediately following it in the caption is the list box’s accelerator key. The accelerator key provides a quick and convenient mechanism for the user to move input focus from one data input control to the list box. The user performs the selection by pressing the Alt key in combination with an accelerator key. The case of an accelerator key is ignored.

MESSAGE cMessage specifies a character string that is displayed on the Get system’s status bar line when the GET has input focus. Typically, it describes the anticipated contents or user response of the GET. Refer to the READ command for details pertaining to the Get system’s status bar.

WHEN lPreExpression specifies an expression that must be satisfied before the cursor can enter the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

VALID lPostExpression specifies an expression that must be satisfied before the cursor can leave the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

COLOR cColorString defines the color settings for the list box. cColorString is a character expression containing exactly seven color settings if there is no drop-down list box, and eight if there is a drop-down list box.

ListBox Color Attributes

Note: In graphic mode, colorSpec position 8 has no affect and is ignored.

FOCUS fblock specifies a code block that is evaluated each time the list box receives focus. The code block takes no implicit arguments. Use the PushButton:hasFocus instance variable to determine if the push button has focus.

STATE bBlock specifies a code block that is evaluated immediately after the list box object’s selection changes. The code block takes no implicit arguments. Use the ListBox:buffer instance variable to determine the current selection.

DROPDOWN indicates that the list box will be a drop-down list box. Drop-down list boxes are displayed differently on the screen than regular list boxes. A regular list box is always displayed regardless of whether it has input focus. A drop-down list box’s display behavior is determined by whether it is closed or open. By default, a drop-down list box is closed. In this case, only the caption, the selected item, and the open button are displayed.

When open, the actual list box is displayed in addition to the caption, selected item, and open button.

Drop-down list boxes are useful in situations where screen space is limited.

SCROLLBAR indicates that the list box will be created with a scroll bar whether or not it is needed. Normally a scroll bar is not needed if the data being displayed fits inside the list box.

SEND msg sends the specified message to the Get object. msg is sent before the GET is displayed. Any message can be sent, including method calls and instance variable assignments. Method calls must include parentheses even if no arguments are passed.

GUISEND guimsg can be used to send a message (such as the display() method) to a GUI object. The GUI objects available in CA-Clipper are check boxes, list boxes, push buttons, and radio button groups. To send a message to a non-GUI object, such as standard GETs and TBrowses, use the SEND clause.

BITMAP cBitmap defines the bitmap that will be used as the down arrow on a drop-down list box. Drive and directory names are not allowed; the file name extension is required. A bitmap file can be stored as a file on disk or in a bitmap library. If stored as a file, the file must reside in the same directory as the application. If stored in a bitmap library, the library must reside in the same directory as the application and it also must have the same name as the application with a .bml extension.

CA-Clipper will search for the file name first and, if it is not found, search in the bitmap library second. If no file is found either on disk or in the library, no bitmap will be displayed.

■  This example demonstrates how to add a list box to a data
   entry screen.  It utilizes the position-oriented method of selection:

   nColor := 1     //default to the first item.
   @ 5, 20, 8, 28 GET nColor LISTBOX { "Red", Green", "Blue" }

■  This example demonstrates a list box that has a caption and a
   message.  It utilizes the data-oriented method of selection:

   cColor := "Red" //default to red.
   @ 5, 20, 8, 28 GET cColor LISTBOX { "Red", Green", "Blue" };
           CAPTION "&Color" ;
           MESSAGE "Select the background color"

■  This example demonstrates a list box that utilizes a two-
   dimensional array.

   cState := "NY"

   @ 5, 20, 10, 30 GET cState LISTBOX { { "Alabama", "AL" }, ;
                                { "Alaska", AK" }   , ;
                                { "Arizona", "AZ" }, ;
                                { etc...          } } ;
           CAPTION "&State" ;
           MESSAGE "Select the client's state"

@ <nRow>, <nCol>
   GET <lVar>
   PUSHBUTTON
      [CAPTION<cCaption>]
      [MESSAGE <cMessage>]
      [WHEN <lPreExpression>]
      [VALID <lPostExpression>]
      [COLOR <cColorString>]
      [FOCUS <fblock>
      [STATE <bBlock>]
      [STYLE <cStyle>]
      [SEND <msg>]
      [GUISEND <guimsg>]
      [SIZE X <nSizeX> Y <nSizeY>]
      [CAPOFF X <nCapXOff> Y <nCapYOff>]
      [BITMAP <cBitmap>]
      [BMPOFF X <nBmpXOff> Y <nBmpYOff>]

nRow and nCol specify the row and column coordinates for the push button and its caption. Output which extends beyond the visible extent of the display is clipped and does not appear.

GET lVar specifies the name of the variable associated with the GET. lVar may contain a value of any type, but upon return from the READ, will always contain logical false (.F.). The purpose of lVar is to provide a place holder in the GetList for the push button.

CAPTION cCaption specifies a character string that concisely describes the GET on the screen. caption differs from the SAY argument in two ways. The first is that the caption is displayed each time the GET is shown on the screen. The other difference is that the caption, along with its screen position, is maintained within the Get object. This allows the GET to receive input when the mouse’s left button is clicked and its cursor is on the caption. By default, the caption appears within the push button’s border. Use the Get object’s capRow or capCol variable to change the screen position of the caption.

When present, the & character specifies that the character immediately following it in the caption is the push button’s accelerator key. The accelerator key provides a quick and convenient mechanism for the user to move input focus from one data input control to the push button. The case of an accelerator key is ignored.

MESSAGE cMessage specifies a character string that is displayed on the Get system’s status bar line when the GET has input focus. Typically, it describes the anticipated contents or user response of the GET. Refer to the READ command for details pertaining to the Get system’s status bar.

WHEN lPreExpression specifies an expression that must be satisfied before the cursor can enter the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

VALID lPostExpression specifies an expression that must be satisfied before the cursor can leave the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

COLOR cColorString defines the color settings for the push button. cColorString is a character expression containing exactly four color settings.

PushButton Color Attributes

Note: The background colors of the PushButton Color Attributes are ignored in graphic mode.

FOCUS fblock specifies a code block that is evaluated each time the push button recieves focus. The code block takes no implicit arguments. Use the PushButton:hasFocus instance variable to determine if the push button has focus.

STATE bBlock specifies a code block that is evaluated each time the push button object’s state changes. The code block takes no implicit arguments. Use the PushButton:buffer instance variable to determine if the push button is pressed or released. A value of true (.T.) indicates that it is being pressed; otherwise, a value of false (.F.) indicates that it is being released.

STYLE cStyle specifies a character string that indicates the delimiter characters that are used by the push button’s display() method. When specified, the string must contain either zero, two, or eight characters. The default is two characters. The first is the left delimiter. Its default value is the less than () character. The second character is the right delimiter. Its default value is the greater than () character.

When the style string is empty, the button has no delimiters. When the string length is two, the button has left and right delimiters and occupies one row on the screen. The first character is the left delimiter. The second character is the right delimiter. When the string length is eight, the button is contained within a box that occupies three rows on the screen.

Standard Box Types

Box.ch contains manifest constants for the PushButton:style value.

The default style for the @...GET PUSHBUTTON is «<>».

Note: The Style clause is ignored in graphic mode.

SEND msg sends the specified message to the Get object. msg is sent before the GET is displayed. Any message can be sent, including method calls and instance variable assignments. Method calls must include parentheses even if no arguments are passed.

GUISEND guimsg can be used to send a message (such as the display() method) to a GUI object. The GUI objects available in CA-Clipper are check boxes, list boxes, push buttons, and radio button groups. To send a message to a non-GUI object, such as standard GETs and TBrowses, use the SEND clause.

SIZE X nSizeX Y nSizeY defines the size of the button to be displayed. The coordinates are in pixels. nSizeX represents the number of pixels in the x direction (horizontally) and nSizeY represents the number of pixels in the y direction (vertically). This argument only affects applications running in graphic mode and is ignored in text mode.

CAPOFF X nCapXOff Y nCapYOff defines the offset where the caption is displayed. The coordinates are in pixels. nCapXOff represents the number of pixels in the x direction (horizontally) from the left edge of the button where the caption will be displayed. nCapYOff represents the number of pixels in the y direction (vertically) from the top edge of the button where the caption will be displayed. If the CAPOFF clause is not supplied, the caption will be centered on the button. This argument only affects applications running in graphic mode and is ignored in text mode.

BITMAP cBitmap defines a bitmap file to be displayed on the button. Drive and directory names are not allowed; the file name extension is required. A bitmap file can be stored as a file on disk or in a bitmap library. If stored as a file, the file must reside in the same directory as the application. If stored in a bitmap library, the library must reside in the same directory as the application and it also must have the same name as the application with a .bml extension.

CA-Clipper will search for the file name first and, if it is not found, search in the bitmap library second. If no file is found either on disk or in the library, no bitmap will be displayed.

BMPOFF X nBmpXOff Y nBmpYOff defines the offset where the bitmap is displayed. The coordinates are in pixels. nCapXOff represents the number of pixels in the x direction (horizontally) from the left edge where the bitmap will be displayed. nCapYOff represents the number of pixels in the y direction (vertically) from the top edge where the bitmap will be displayed. If the BMPOFF clause is not supplied, the bitmap will be placed at the upper-left corner of the button. This argument only affects applications running in graphic mode and is ignored in text mode.

■  This example demonstrates how to add a push button to a data
   entry screen:

   @ 5, 20 GET lCancel PUSHBUTTON ;
           CAPTION "&Cancel"
           STATE { || ReadKill( .T. ) }

@ <nTop>, <nLeft>, <nBottom>, <nRight>
   GET <nVar|cVar>
   RADIOGROUP <aGroup>
      [CAPTION<cCaption>]
      [MESSAGE <cMessage>]
      [COLOR <cColorString>]
      [FOCUS] <fblock>
      [WHEN <lPreExpression>]
      [VALID <lPostExpression>]
      [SEND <msg>]
      [GUISEND <guimsg>]

nTop, nLeft, nBottom and nRight specify the screen position for the radio button group and its caption. Output which extends beyond the visible extent of the display is clipped and does not appear.

GET nVar|cVar specifies the name of the variable associated with the GET. Its value indicates which radio button (if any) in the group is selected. A numeric value refers to the position in the group of the selected button. A value of 0 indicates no selected button. A character string value refers to the data or text contained within the selected button. A character string that does not refer to any item in the list indicates no selected item.

RADIOGROUP aGroup specifies an array of RadioButto objects.

CAPTION cCaption specifies a character string that concisely describes the GET on the screen. Caption differs from the SAY argument in two ways. The first is that the caption is displayed each time the GET is shown on the screen. The other difference is that the caption, along with its screen position is maintained within the Get object. This allows the GET to receive input when the mouse’s left button is clicked and its cursor is on the caption. By default, the caption appears in the top-left border of the GET. Use the Get object’s capRow or capCol variable to change the screen position of the caption.

When present, the & character specifies that the character immediately following it in the caption is the radio group’s accelerator key. The accelerator key provides a quick and convenient mechanism for the user to move input focus from one data input control to the radio group. The case of an accelerator key is ignored.

MESSAGE cMessage specifies a character string that is displayed on the Get system’s status bar line when the GET has input focus. Typically, it describes the anticipated contents or user response of the GET. Refer to the READ command for details pertaining to the Get system’s status bar.

COLOR cColorString defines the color settings for the radio button group. cColorString is a character expression containing exactly three color settings.

RadioGroup Color Attributes

FOCUS fblock specifies a code block that is evaluated each time the radio button group receives focus. The code block takes no implicit arguments. Use the RadioGroup:hasFocus instance variable to determine if the radio group has focus.

WHEN lPreExpression specifies an expression that must be satisfied before the cursor can enter the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

VALID lPostExpression specifies an expression that must be satisfied before the cursor can leave the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

Note: There is no STATE clause for the @...GET RADIOGROUP command. Instead each radio button in the group can have its own sBlock instance variable. See sBlock under RadioButto class for more details.

SEND msg sends the specified message to the Get object. msg is sent before the GET is displayed. Any message can be sent, including method calls and instance variable assignments. Method calls must include parentheses even if no arguments are passed.

GUISEND guimsg can be used to send a message (such as the display() method) to a GUI object. The GUI objects available in CA-Clipper are check boxes, list boxes, push buttons, and radio button groups. To send a message to a non-GUI object, such as standard GETs and TBrowses, use the SEND clause.

■  This example demonstrates how to add a radio button group to a
   data entry screen.  It utilizes a position-oriented method of
   selection:

   nColor := 1            //default to the first item.
   aGroup := Array( 3 )
   aGroup[ 1 ] := RadioButto( 6, 22, "&Red" )
   aGroup[ 2 ] := RadioButto( 7, 22, "&Green" )
   aGroup[ 3 ] := RadioButto( 8, 22, "&Blue" )
   @ 5, 20, 9, 40 GET nColor RADIOGROUP aGroup

  The nColor variable will return a position, in this case 1, 2, or 3.

■  This example demonstrates a radio button group that utilizes a
   data-oriented method of selection:

   cColor := "R"          //default to red.
   aGroup := Array( 3 )
   aGroup[ 1 ] := RadioButto( 6, 22, "&Red", "R" )
   aGroup[ 2 ] := RadioButto( 7, 22, "&Green", "G" )
   aGroup[ 3 ] := RadioButto( 8, 22, "&Blue", "B" )
   @ 5, 15, 9, 40 GET cColor RADIOGROUP aGroup

  The nColor variable will return data, in this case "R", "G", or "B".

@ <nTop>, <nLeft>, <nBottom>, <nRight>
   GET <idVar>
   TBROWSE <oBrowse>
      [MESSAGE <cMessage>]
      [WHEN <lPreExpression>]
      [VALID <lPostExpression>]
      [SEND <msg>]
      [GUISEND <guimsg>]

nTop, nLeft, nBottom and nRight specify the screen position for the TBrowse object. Output which extends beyond the visible extent of the display is clipped and does not appear.

GET idVar specifies the name of the variable associated with the GET. Its value is neither queried nor modified by the Get system. The GET is merely a mechanism used for integrating a TBrowse object into the @...GET/READ system.

TBROWSE oTBrowse specifies a previously defined TBrowse object.

MESSAGE cMessage specifies a character string that is displayed on the Get system’s status bar line when the GET has input focus. Typically, it describes the anticipated contents or user response of the GET. Refer to the READ command for details pertaining to the Get system’s status bar.

WHEN lPreExpression specifies an expression that must be satisfied before the cursor can enter the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

VALID lPostExpression specifies an expression that must be satisfied before the cursor can leave the GET during a READ. The expression can optionally be a code block. The Get object is passed as a parameter to the code block.

SEND msg sends the specified message to the Get object. msg is sent before the GET is displayed. Any message can be sent, including method calls and instance variable assignments. Method calls must include parentheses even if no arguments are passed.

GUISEND guimsg can be used to send a message (such as the display() method) to a GUI object. The GUI objects available in CA-Clipper are check boxes, list boxes, push buttons, and radio button groups. To send a message to a non-GUI object, such as standard GETs and TBrowses, use the SEND clause.

■  This example demonstrates how to add a TBrowse object to a
   data entry screen:

   oTB := TBrowseDB( 10, 10, 15, 40 )
   oTB:AddColumn(TBColumnNew("Last Name",{||Customer->lName}))
   oTB:AddColumn(TBColumnNew("First Name",{||Customer->fName}))
   oTB:AddColumn(TBColumnNew("Phone",{||Customer->Phone}))
   uDummy := NIL
   @ 10, 10, 15, 40 GET uDummy TBROWSE oTB

@ <nRow>, <nCol> PROMPT <cMenuItem>
   [MESSAGE <cExpression>]

nRow and nCol are the row and column coordinates of the menu item display. Row values can range from zero to MaxRow(), and column values can range from zero to MaxCol().

PROMPT cMenuItem is the menu item string to display.

MESSAGE cExpression defines the message to display each time the current menu item is highlighted. A code block evaluating to a character expression may optionally be used.

@...PROMPT is the display portion of the CA-Clipper lightbar menu system. Each @...PROMPT command paints a menu item in the current standard color and defines an associated MESSAGE to be displayed on the line specified by SET MESSAGE. The lightbar menu is then invoked with MENU TO. You can specify menu items in any order and configuration of row and column position. MENU TO, however, navigates the current list of menu items in the order they were defined. You can define up to 4096 menu items for each menu.

After each @...PROMPT command, the cursor is located one column position to the right of the last menu item character and Row() and Col() are updated to reflect the new cursor position. This lets you use Row() and Col() to specify consecutive menu item positions relative to the first one painted. See the example below.

■  This example displays a lightbar menu with the associated
   messages displayed on the next line.  When the user presses Return,
   the position of the item in the list of menu items is assigned to
   nChoice:

   LOCAL nChoice := 1
   SET WRAP ON
   SET MESSAGE TO 2
   @ 1, 3 PROMPT "File" MESSAGE "Access data files"
   @ Row(), Col() + 2 PROMPT "Edit" ;
      MESSAGE "Edit current record"
   MENU TO nChoice

■  This example shows how to pass the MESSAGE clause a code block
   which calls a user-defined function that displays a message in a
   different color:

   SET COLOR TO gr+/b,r+/n
   SET MESSAGE TO 23    // This is necessary.
   CLEAR SCREEN

   @ 3,4 PROMPT "one "  MESSAGE {||UDF("Message One  ")}
   @ 4,4 PROMPT "two "  MESSAGE {||UDF("Message Two  ")}
   @ 5,4 PROMPT "three" MESSAGE {||UDF("Message Three")}

   MENU TO test

   FUNCTION UDF(cParm)
   cOldColor := SetColor("w+/n")
   @ 22,1 SAY cParm        // Must be different row than the
                           // SET MESSAGE TO nRow
   SetColor(cOldColor)
   RETURN ""               // Character string must be returned

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

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. Also, 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 a character, date, logical, or numeric expression to the current DEVICE.

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

COLOR cColorString defines the display color of exp. If not specified, exp displays in the standard color as defined by SetColor(). cColorString is a character expression containing the standard color setting. If you specify a literal color setting, it must be enclosed in quote marks.

On a combined @...SAY...GET command, two COLOR clauses are required to specify colors for both the SAY and the GET: one for the SAY and one for the GET.

@...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 creates data entry screens or reports that can be sent to the screen or printer.

When an @...SAY command executes , the output from exp is sent to the current device defined with SET DEVICE. The current DEVICE can 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 beyond the visible screen. All @...SAY output displays are in standard color. Refer to the SetColor() reference in this chapter for more information on color.

If the current DEVICE is set to PRINTER, the display is directed to the printer at the specified nRow and nCol position. If the 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 differently from those 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 linefeed 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 and 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() function reference for more information.

If the current DEVICE is the PRINTER, redirect output from @...SAY commands to a file using the SET PRINTER TO xcFile command.

@...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 on the entire @...SAY output. 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 entire display value, 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). 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.

SAY and Transform() PICTURE Format Functions

■ 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 that do not have assigned meanings are copied verbatim into the displayed SAY value. If you use the @R picture function, characters without special PICTURE template string meaning are inserted between characters of the display value; otherwise, they overwrite the corresponding characters of the display value. You may specify a template string 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.

SAY and Transform() Template Symbols

■  This example uses an @...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

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

nTop, nLeft, nBottom, and nRight define the coordinates of the box. @...TO draws the box 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 drawn box. 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 specify a literal color setting, enclose it within quote marks.

@...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 like @...BOX except that @...BOX lets you 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.

■  This example erases a region of the screen, then draws a box
   of the same size:

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

■  This example illustrates the case-sensitivity of the substring
   operator ($):

   ? "A" $ "ABC"            // Result: .T.
   ? "a" $ "ABC"            // Result: .F.

■  This example shows multiplication results using different
   operands:

   ?  3 *  0            // Result:  0
   ?  3 * -2            // Result: -6
   ? -3 *  2            // Result: -6
   ? -3 *  0            // Result:  0
   ? -1 *  3            // Result: -3
   ? -2 * -3            // Result:  6
   ?  2 * -3            // Result: -6
   ?  1 * -3            // Result: -3

<nNumber1> ** <nNumber2>
<nNumber1> ^  <nNumber2>

■  This example shows exponentiation results to 16 decimal
   places, using different operands:

   SET DECIMALS TO 16
   ?  3 **  0            // Result:  1.000000000
   ?  3 **  1            // Result:  3.000000000
   ?  3 ** -2            // Result:  0.111111111
   ? -3 **  2            // Result:  9.000000000
   ? -3 **  0            // Result:  1.000000000
   ? -1 **  3            // Result: -1.000000000
   ? -2 **  3            // Result: -8.000000000
   ?  2 ** -3            // Result:  0.125000000
   ?  1 ** -3            // Result:  1.000000000

&<cMacroVar>[.]
&(<cMacroExp>)

The macro operator in CA-Clipper is a special operator that allows runtime compilation of expressions and text substitution within strings. Whenever the macro operator (&) is encountered, the operand is submitted to a special runtime compiler (the macro compiler) that compiles expressions, but not statements or commands.

Text Substitution

Whenever a reference to a private or public macro variable, embedded in a character string, is encountered, the variable reference is replaced by the content of the macro variable. For example,

cMacro := «there» ? «Hello &cMacro» // Result: Hello there

If you specify a macro expression (e.g., &(cMacro1 + cMacro2)), and the macro variable is a local, static, field variable, or an array element, it is treated as literal text and not expanded.

Macro operator:nesting Compile and Run

When a macro variable or expression specified within an expression is encountered, it is treated like an expression, with the macro symbol behaving as the compile and run operator. If the macro is specified as a macro variable,

cMacro := «DToC(Date())» ? &cMacro

the macro compiler compiles, then executes the content of the macro variable. The compiled code is then discarded.

If you specify an expression enclosed in parentheses and prefaced by the macro operator (&),

? &(IndexKey(0))

the expression is evaluated and the resulting character string is compiled and run as a macro variable.

Using the macro operator, you can compile a character string containing a code block definition:

bBlock := &(«{ |exp| QOut(exp) }»)

The run portion of the operation returns the code block as a value. You may then use the code block by invoking it with the Eval() function. This is especially significant in activations that involve extensive looping through user-defined conditions (operations that in earlier versions of CA-Clipper required macro expansion). In those versions, the macro expression was compiled and run for each iteration of the loop. With the combination of a macro expansion and a code block Eval(), the compilation is performed once at compile time, and the Eval() merely executes the code block each time through the loop:

Eval(bBlock, Date())

The time savings at runtime can be enormous.

■ Command keywords: You cannot use the macro operator (&) to

substitute or compile command keywords. However, you can redefine command keywords by modifying the command definition in std.ch, overriding an existing command definition with a new definition using the #command directive, or redefining a command keyword using the #translate directive. In any case, you may redefine a command keyword only at compile time, not at runtime.

■ Command arguments: In prior versions of CA-Clipper as well as

in other dialects, you could use macro variables as the arguments of commands requiring literal text values. These included all file command arguments and SET commands with toggle arguments. In these instances, you can now use an extended expression enclosed in parentheses in place of the literal argument. For example,

xcDatabase = «Invoices» USE &xcDatabase.

can be replaced with:

xcDatabase = «Invoices» USE (xcDatabase)

It is important to use extended expressions if you are using local and static variables. Generally, commands are preprocessed into function calls with command arguments translated into function arguments as valid CA-Clipper values. File names in file commands, for instance, are stringified using the smart stringify result marker and passed as arguments to the functions that actually perform the desired actions. If you specify a literal or macro value as the command argument, it is stringified. If, however, the argument is an extended expression, it is written to the result text exactly as specified. This example,

#command RENAME xcOld TO xcNew; =>;

FRename( (xcOld), (xcNew) )

// RENAME &xcOld TO &xcNew RENAME (xcOld) TO (xcNew)

is written to the result text as this:

FRename( «&xcOld», «&xcNew» ) FRename( xcOld, xcNew )

when preprocessed. When the macro variables are stringified, the macro variable names are hidden in the string and not compiled. Later, at runtime, they are substituted into the string and passed as arguments to the FRename() function. This precludes local and static macro variables since the names of the variables are not present at runtime to be substituted. Public and private variables, however, behave as expected.

■ Lists as arguments of commands: The macro operator (&) will

not fully substitute or compile a list as an argument of most commands. In particular, these are commands where an argument list is preprocessed into an array or a code block. Instances of this are arguments of the FIELDS clause and SET INDEX. An exception is the SET COLOR command which preprocesses the list of colors into a single character string and passes it to the SetColor() function.

In any case, list arguments should always be specified as extended expressions with each list argument specified:

LOCAL xcIndex := { «Ntx1», «Ntx2» } SET INDEX TO (xcIndex[1]), (xcIndex[2])

■ Arrays: You can use the macro operator (&) with arrays and

array elements. However, because of the increased power of CA-Clipper arrays, you may find less need to use the macro operator (&) to make variable references to arrays. You can now assign array references to variables, return array references from user-defined functions, and nest array references within other arrays. You may also create arrays by specifying literal arrays or using the Array() function.

You can, therefore, make references to arrays and array elements using both macro variables and macro expressions with the restriction that you cannot make the subscript references in a PRIVATE or PUBLIC statement. Also, you cannot specify the macro operator (&) in a declaration statement, such as a LOCAL or STATIC statement. Attempting this will generate a fatal compiler error.

This example references array elements using macro variables:

cName := «aArray» nElements := 5 cNameElement := «aArray[1]» // PRIVATE &cName.[nElements] // Creates «array» with 5

// elements

&cNameElement. := 100 // Assigns 100 to element 1 &cName.[3] := «abc» // Assigns «abc» to element 3

You can successfully apply a macro operator (&) to an array element if the reference is made using a macro expression. A macro variable reference, however, will generate a runtime error. For example, the following lists the values of all fields of the current record:

USE Customer NEW aStruc := dbStruct() // FOR nField := 1 TO Len(aStruc)

? &(aStruc[nField, 1])

NEXT

■ Code blocks: You can apply the macro operator (&) to a macro

variable or expression in a code block in most cases. There is a restriction when the macro variable or macro expression contains a declared variable. A runtime error occurs if you specify a complex expression (an expression that contains an operator and one or more operands) that includes the macro operator (&) within a code block.

This has important implications for the use of local and static variables in the conditional clauses of commands, since these clauses are blockified as they are written to the result text during preprocessing. This applies to all FOR and WHILE clauses, the SET FILTER command, and the SET RELATION linking expression. The general workaround is to gather the entire expression into a single macro variable then apply the macro operator (&) to the variable.

■ Macro conditions: When using the macro operator (&) to specify

conditional clauses of database commands such as FOR or WHILE clauses, there are some restrictions based on the expression’s complexity and size:

— The maximum string size the macro compiler can process is 254

characters.

— There is a limit to the complexity of conditions (the more

complex, the fewer the number of conditions you can specify).

■ Procedures and functions: You can reference procedure and

function calls using macro variables and expressions. With DO, the macro variable reference to the procedure can be all or part of the procedure name. With a call to a function (built-in or user- defined), the macro variable reference must include the function name and all of its arguments.

In CA-Clipper, because of the added facility code blocks, all invocations of procedures and functions using the macro operator should be converted to the evaluation of code blocks. This code fragment

cProc := «AcctsRpt» . . . DO &cProc

can be replaced with:

bProc := &( «{ || AcctsRpt() }» ) . . . Eval(bProc)

The advantage of a code block over a macro evaluation is that the result of the compilation of a string containing a code block can be saved and, therefore, need only be compiled once. Macro evaluations compile each time they are referenced.

■ References into overlays: You must declare procedures and

user-defined functions that are used in macro expressions and variables but not referenced elsewhere as EXTERNAL, or the linker will not include them into the executable (.EXE) file.

■ TEXT...ENDTEXT: Macro variables referenced within a

TEXT...ENDTEXT construct are expanded. Note that a field cannot be expanded, so you must first assign the field value to a memory variable then reference the memory variable as a macro variable within the TEXT...ENDTEXT. For example:

USE Customer NEW myVar := Customer->CustName TEXT This is text with a macro &myVar ENDTEXT

■ Nested macros: The processing of macro variables and

expressions in CA-Clipper permits nested macro definitions. For example, after assigning a macro variable to another macro variable, the original macro variable can be expanded resulting in the expansion of the second macro variable and evaluation of its contents:

cOne = «&cTwo» // expand cTwo cTwo = «cThree» // yielding «cThree» cThree = «hello» // ? &cOne // Result: «hello»

#command   <matchPattern> => <resultPattern>
#translate   <matchPattern> => <resultPattern>

matchPattern is the pattern the input text should match.

resultPattern is the text produced if a portion of input text matches the matchPattern.

The => symbol between matchPattern and resultPattern is, along with #command or #translate, a literal part of the syntax that must be specified in a #command or #translate directive. The symbol consists of an equal sign followed by a greater than symbol with no intervening spaces. Do not confuse the symbol with the >= or the <= comparison operators in the CA-Clipper language.

#command and #translate are translation directives that define commands and pseudofunctions. Each directive specifies a translation rule. The rule consists of two portions: a match pattern and a result pattern. The match pattern matches a command specified in the program (.prg) file and saves portions of the command text (usually command arguments) for the result pattern to use. The result pattern then defines what will be written to the result text and how it will be written using the saved portions of the matching input text.

#command and #translate are similar, but differ in the circumstance under which their match patterns match input text. A #command directive matches only if the input text is a complete statement, while #translate matches input text that is not a complete statement. #command defines a complete command and #translate defines clauses and pseudofunctions that may not form a complete statement. In general, use #command for most definitions and #translate for special cases.

#command and #translate are similar to but more powerful than the #define directive. #define, generally, defines identifiers that control conditional compilation and manifest constants for commonly used constant values such as Inkey() codes. Refer to any of the header files in the CLIP53INCLUDE directory for examples of manifest constants defined using #define.

#command and #translate directives have the same scope as the #define directive. The definition is valid only for the current program (.prg) file unless defined in std.ch or the header specified with the /U option on the compiler command line. If defined elsewhere, the definition is valid from the line where it is specified to the end of the program file. Unlike #define, a #translate or #command definition cannot be explicitly undefined. The #undef directive has no effect on a #command or #translate definition.

As the preprocessor encounters each source line preprocessor, it scans for definitions in the following order of precedence: #define, #translate, and #command. When there is a match, the substitution is made to the result text and the entire line is reprocessed until there are no matches for any of the three types of definitions. #command and #translate rules are processed in stack-order (i.e., last in-first out, with the most recently specified rule processed first).

In general, a command definition provides a way to specify an English language statement that is, in fact, a complicated expression or function call, thereby improving the readability of source code. You can use a command in place of an expression or function call to impose order of keywords, required arguments, combinations of arguments that must be specified together, and mutually exclusive arguments at compile time rather than at runtime. This can be important since procedures and user-defined functions can now be called with any number of arguments, forcing any argument checking to occur at runtime. With command definitions, the preprocessor handles some of this.

All commands in CA-Clipper are defined using the #command directive and supplied in the standard header file, std.ch, located in the CLIP53INCLUDE directory. The syntax rules of #command and #translate facilitate the processing of all CA-Clipper and dBASE-style commands into expressions and function calls. This provides CA-Clipper compatibility, as well as avenues of compatibility with other dialects.

When defining a command, there are several prerequisites to properly specifying the command definition. Many preprocessor commands require more than one #command directive because mutually exclusive clauses contain a keyword or argument. For example, the @...GET command has mutually exclusive VALID and RANGE clauses and is defined with a different #command rule to implement each clause.

This also occurs when a result pattern contains different expressions, functions, or parameter structures for different clauses specified for the same command (e.g., the @...SAY command). In std.ch, there is a #command rule for @...SAY specified with the PICTURE clause and another for @...SAY specified without the PICTURE clause. Each formulation of the command is translated into a different expression. Because directives are processed in stack order, when defining more than one rule for a command, place the most general case first, followed by the more specific ones. This ensures that the proper rule will match the command specified in the program (.prg) file.

For more information and a general discussion of commands, refer to the «Basic Concepts» chapter in the Programming and Utilities Guide.

Match Pattern

The matchPattern portion of a translation directive is the pattern the input text must match. A match pattern is made from one or more of the following components, which the preprocessor tries to match against input text in a specific way:

■ Literal values are actual characters that appear in the match

pattern. These characters must appear in the input text, exactly as specified to activate the translation directive.

■ Words are keywords and valid identifiers that are compared

according to the dBASE convention (case-insensitive, first four letters mandatory, etc.). The match pattern must start with a Word.

#xcommand and #xtranslate can recognize keywords of more than four significant letters.

■ Match markers are label and optional symbols delimited by

angle brackets (<>) that provide a substitute (idMarker) to be used in the resultPattern and identify the clause for which it is a substitute. Marker names are identifiers and must, therefore, follow the CA-Clipper identifier naming conventions. In short, the name must start with an alphabetic or underscore character, which may be followed by alphanumeric or underscore characters.

This table describes all match marker forms:

Match Markers

— Regular match marker: Matches the next legal expression in the

input text. The regular match marker, a simple label, is the most general and, therefore, the most likely match marker to use for a command argument. Because of its generality, it is used with the regular result marker, all of the stringify result markers, and the blockify result marker.

— List match marker: Matches a comma-separated list of legal

expressions. If no input text matches the match marker, the specified marker name contains nothing. You must take care in making list specifications because extra commas will cause unpredictable and unexpected results.

The list match marker defines command clauses that have lists as arguments. Typically these are FIELDS clauses or expression lists used by database commands. When there is a match for a list match marker, the list is usually written to the result text using either the normal or smart stringify result marker. Often, lists are written as literal arrays by enclosing the result marker in curly ({ }) braces.

— Restricted match marker: Matches input text to one of the

words in a comma-separated list. If the input text does not match at least one of the words, the match fails and the marker name contains nothing.

A restricted match marker is generally used with the logify result marker to write a logical value into the result text. If there is a match for the restricted match marker, the corresponding logify result marker writes true (.T.) to the result text; otherwise, it writes false (.F.). This is particularly useful when defining optional clauses that consist of a command keyword with no accompanying argument. std.ch implements the REST clause of database commands using this form.

— Wild match marker: Matches any input text from the current

position to the end of a statement. Wild match markers generally match input that may not be a legal expression, such as #command NOTE *x* in std.ch, gather the input text to the end of the statement, and write it to the result text using one of the stringify result markers.

— Extended expression match marker: Matches a regular or

extended expression, including a file name or path specification. It is used with the smart stringify result marker to ensure that extended expressions will not get stringified, while normal, unquoted string file specifications will.

■ Optional match clauses are portions of the match pattern

enclosed in square brackets ([ ]). They specify a portion of the match pattern that may be absent from the input text. An optional clause may contain any of the components allowed within a matchPattern, including other optional clauses.

Optional match clauses may appear anywhere and in any order in the match pattern and still match input text. Each match clause may appear only once in the input text. There are two types of optional match clauses: one is a keyword followed by match marker, and the other is a keyword by itself. These two types of optional match clauses can match all of the traditional command clauses typical of the CA-Clipper command set.

Optional match clauses are defined with a regular or list match marker to match input text if the clause consists of an argument or a keyword followed by an argument (see the INDEX clause of the USE command in std.ch). If the optional match clause consists of a keyword by itself, it is matched with a restricted match marker (see the EXCLUSIVE or SHARED clause of the USE command in std.ch).

In any match pattern, you may not specify adjacent optional match clauses consisting solely of match markers, without generating a compiler error. You may repeat an optional clause any number of times in the input text, as long as it is not adjacent to any other optional clause. To write a repeated match clause to the result text, use repeating result clauses in the resultPattern definition.

Result Pattern

The resultPattern portion of a translation directive is the text the preprocessor will produce if a piece of input text matches the matchPattern. resultPattern is made from one or more of the following components:

■ Literal tokens are actual characters that are written directly

to the result text.

■ Words are CA-Clipper keywords and identifiers that are written

directly to the result text.

■ Result markers: refer directly to a match marker name. Input

text matched by the match marker is written to the result text via the result marker.

This table lists the Result marker forms:

Result Markers

— Regular result marker: Writes the matched input text to the

result text, or nothing if no input text is matched. Use this, the most general result marker, unless you have special requirements. You can use it with any of the match markers, but it almost always is used with the regular match marker.

— Dumb stringify result marker: Stringifies the matched input

text and writes it to the result text. If no input text is matched, it writes a null string («»). If the matched input text is a list matched by a list match marker, this result marker stringifies the entire list and writes it to the result text.

This result marker writes output to result text where a string is always required. This is generally the case for commands where a command or clause argument is specified as a literal value but the result text must always be written as a string even if the argument is not specified.

— Normal stringify result marker: Stringifies the matched input

text and writes it to the result text. If no input text is matched, it writes nothing to the result text. If the matched input text is a list matched by a list match marker, this result marker stringifies each element in the list and writes it to the result text.

The normal stringify result marker is most often used with the blockify result marker to compile an expression while saving a text image of the expression (See the SET FILTER condition and the INDEX key expression in std.ch).

— Smart stringify result marker: Stringifies matched input text

only if source text is enclosed in parentheses. If no input text matched, it writes nothing to the result text. If the matched input text is a list matched by a list match marker, this result marker stringifies each element in the list (using the same stringify rule) and writes it to the result text.

The smart stringify result marker is designed specifically to support extended expressions for commands other than SETs with xlToggle arguments. Extended expressions are command syntax elements that can be specified as literal text or as an expression if enclosed in parentheses. The xcDatabase argument of the USE command is a typical example. For instance, if the matched input for the xcDatabase argument is the word Customer, it is written to the result text as the string «Customer,» but the expression (cPath + cDatafile) would be written to the result text unchanged (i.e., without quotes).

— Blockify result marker: Writes matched input text as a code

block without any arguments to the result text. For example, the input text x + 3 would be written to the result text as {|| x + 3}. If no input text is matched, it writes nothing to the result text. If the matched input text is a list matched by a list match marker, this result marker blockifies each element in the list.

The blockify result marker used with the regular and list match markers matches various kinds of expressions and writes them as code blocks to the result text. Remember that a code block is a piece of compiled code to execute sometime later. This is important when defining commands that evaluate expressions more than once per invocation. When defining a command, you can use code blocks to pass an expression to a function and procedure as data rather than as the result of an evaluation. This allows the target routine to evaluate the expression whenever necessary.

In std.ch, the blockify result marker defines database commands where an expression is evaluated for each record. Commonly, these are field or expression lists, FOR and WHILE conditions, or key expressions for commands that perform actions based on key values.

— Logify result marker: Writes true (.T.) to the result text if

any input text is matched; otherwise, it writes false (.F.) to the result text. This result marker does not write the input text itself to the result text.

The logify result marker is generally used with the restricted match marker to write true (.T.) to the result text if an optional clause is specified with no argument; otherwise, it writes false (.F.). In std.ch, this formulation defines the EXCLUSIVE and SHARED clauses of the USE command.

■ Repeating result clauses are portions of the resultPattern

enclosed by square brackets ([ ]). The text within a repeating clause is written to the result text as many times as it has input text for any or all result markers within the clause. If there is no matching input text, the repeating clause is not written to the result text. Repeating clauses, however, cannot be nested. If you need to nest repeating clauses, you probably need an additional #command rule for the current command.

Repeating clauses are the result pattern part of the #command facility that create optional clauses which have arguments. You can match input text with any match marker other than the restricted match marker and write to the result text with any of the corresponding result markers. Typical examples of this facility are the definitions for the STORE and REPLACE commands in std.ch.

■ Less than operator: If you specify the less than operator (`)

in the resultPattern expression, you must precede it with the escape character ().

■ Multistatement lines: You can specify more than one statement

as a part of the result pattern by separating each statement with a semicolon. If you specify adjacent statements on two separate lines, the first statement must be followed by two semicolons.

These examples encompass many of the basic techniques you can use when
defining commands with the #command and #translate directives.  In
general, these examples are based on standard commands defined in
Std.ch.  Note, however, the functions specified in the example result
patterns are not the actual functions found in std.ch, but fictitious
functions specified for illustration only.

■  This example defines the @...BOX command using regular match
   markers with regular result markers:

   #command  @ <top>, <left>, <bottom>, <right> BOX ;
         <boxstring>;
   =>;
         CmdBox( <top>, <left>, <bottom>, ;
         <right>,<boxstring> )

■  This example uses a list match marker with a regular result
   marker to define the ? command:

   #command ? [<list,...>] => QOut(<list>)

■  This example uses a restricted match marker with a logify
   result marker to implement an optional clause for a command
   definition.  In this example, if the ADDITIVE clause is specified,
   the logify result marker writes true (.T.) to the result text;
   otherwise, it writes false (.F.):

   #command RESTORE FROM <file> [<add: ADDITIVE>];
   =>;
         CmdRestore( <(file)>, <.add.> )

■  This example uses a list match marker with a smart stringify
   result marker to write to the result text the list of fields
   specified as the argument of a FIELDS clause.  In this example, the
   field list is written as an array with each field name as an element
   of the array:

   #command COPY TO <file> [FIELDS <fields,...>];
   =>;
         CmdCopyAll( <(file)>, { <(fields)> } )

■  These examples use the wild match marker to define a command
   that writes nothing to the result text.  Do this when attempting to
   compile unmodified code developed in another dialect:

   #command SET ECHO <*text*>    =>
   #command SET TALK <*text*>    =>

■  These examples use wild match markers with dumb stringify
   result markers to match command arguments specified as literals, then
   write them to the result text as strings in all cases:

   #command SET PATH TO <*path*>  =>  ;
      Set( _SET_PATH, #<path> )
   #command SET COLOR TO <*spec*> =>  SetColor( #<spec> )

■  These examples use a normal result marker with the blockify
   result marker to both compile an expression and save the text version
   of it for later use:

   #command SET FILTER TO <xpr>;
   =>;
         CmdSetFilter( <{xpr}>, <"xpr"> )

   #command INDEX ON <key> TO <file>;
   =>;
         CmdCreateIndex( <(file)>, <"key">, <{key}> )

■  This example demonstrates how the smart stringify result
   marker implements a portion of the USE command for those arguments
   that can be specified as extended expressions:

   #command USE <db> [ALIAS <a>];
   =>;
         CmdOpenDbf( <(db)>, <(a)> )

■  This example illustrates the importance of the blockify result
   marker for defining a database command.  Here, the FOR and WHILE
   conditions matched in the input text are written to the result text
   as code blocks:

   #command COUNT [TO <var>];
         [FOR <for>] [WHILE <while>];
         [NEXT <next>] [RECORD <rec>] [<rest:REST>] [ALL];
   =>;
         <var> := 0,;
         dbEval( {|| <var>++}, <{for}>, <{while}>,;
            <next>, <rec>, <.rest.> )

■  In this example the USE command again demonstrates the types
   of optional clauses with keywords in the match pattern.  one clause
   is a keyword followed by a command argument, and the second is solely
   a keyword:

   #command USE <db> [<new: NEW>] [ALIAS <a>] ;
         [INDEX <index,...>][<ex: EXCLUSIVE>] ;
         [<sh: SHARED>] [<ro: READONLY>];
   =>;
         CmdOpenDbf(<(db)>, <(a)>, <.new.>,;
            IF(<.sh.> .OR. <.ex.>, !<.ex.>, NIL),;
               <.ro.>, {<(index)>})

■  This example uses the STORE command definition to illustrate
   the relationship between an optional match clause and a repeating
   result clause:

   #command STORE <value> TO <var1> [, <varN> ];
   =>;
         <var1> := [ <varN> := ] <value>

■  This example uses #translate to define a pseudofunction:

   #translate AllTrim(<cString>) => LTrim(RTrim(<cString>))

#define <idConstant> [<resultText>]
#define <idFunction>([<arg list>]) [<exp>]

idConstant is the name of an identifier to define.

resultText is the optional replacement text to substitute whenever a valid idConstant is encountered.

idFunction is a pseudofunction definition with an optional argument list (arg list). If you include arg list, it is delimited by parentheses (()) immediately following idFunction.

exp is the replacement expression to substitute when the pseudofunction is encountered. Enclose this expression in parentheses to guarantee precedence of evaluation when the pseudofunction is expanded.

Note: #define identifiers are case-sensitive, where #command and #translate identifiers are not.

The #define directive defines an identifier and, optionally, associates a text replacement string. If specified, replacement text operates much like the search and replace operation of a text editor. As each source line from a program file is processed by the preprocessor, the line is scanned for identifiers. If a currently defined identifier is encountered, the replacement text is substituted in its place.

Identifiers specified with #define follow most of the identifier naming rules in CA-Clipper . Defined identifiers can contain any combination of alphabetic and numeric characters, including underscores. Defined identifiers, however, differ from other identifiers by being case- sensitive. As a convention, defined identifiers are specified in uppercase to distinguish them from other identifiers used within a program. Additionally, identifiers are specified with a one or two letter prefix to group similar identifiers together and guarantee uniqueness. Refer to one of the supplied header files in the CLIP53INCLUDE directory for examples.

When specified, each definition must occur on a line by itself. Unlike statements, more than one directive cannot be specified on the same source line. You may continue a definition on a subsequent line by employing a semicolon (;). Each #define directive is specified followed by one or more white space characters (spaces or tabs), a unique identifier, and optional replacement text. Definitions can be nested, allowing one identifier to define another.

A defined identifier has lexical scope like a filewide static variable. It is only valid in the program (.prg) file in which it is defined unless defined in std.ch or the header file specified on the compiler command line with the /U option. Unlike a filewide static variable, a defined identifier is visible from the point where it is defined in the program file until it is either undefined, redefined, or the end of the program file is reached.

You can redefine or undefine existing identifiers. To redefine an identifier, specify a new #define directive with the identifier and the new replacement text as its arguments. The current definition is then overwritten with the new definition, and a compiler warning is issued in case the redefinition is inadvertent. To undefine an identifier, specify an #undef directive with the identifier as its argument. #define directives have three basic purposes:

■ To define a control identifier for #ifdef and #ifndef

■ To define a manifest constant—an identifier defined to

represent a constant value

■ To define a compiler pseudofunction

The following discussion expands these three purposes of the #define directive in your program.

Preprocessor Identifiers

The most basic #define directive defines an identifier with no replacement text. You can use this type of identifier when you need to test for the existence of an identifier with either the #ifdef or #ifndef directives. This is useful to either exclude or include code for conditional compilation. This type of identifier can also be defined using the /D compiler option from the compiler command line. See the examples below.

Manifest Constants

The second form of the #define directive assigns a name to a constant value. This form of identifier is referred to as a manifest constant. For example, you can define a manifest constant for the Inkey() code associated with a key press:

#define K_ESC 27 IF LastKey() = K_ESC

. . statements .

ENDIF

Whenever the preprocessor encounters a manifest constant while scanning a source line, it replaces it with the specified replacement text.

Although you can accomplish this by defining a variable, there are several advantages to using a manifest constant: the compiler generates faster and more compact code for constants than for variables; and variables have memory overhead where manifest constants have no runtime overhead, thus saving memory and increasing execution speed. Furthermore, using a variable to represent a constant value is conceptually inconsistent. A variable by nature changes and a constant does not.

Use a manifest constant instead of a constant for several reasons. First, it increases readability. In the example above, the manifest constant indicates more clearly the key being represented than does the Inkey() code itself. Second, manifest constants localize the definition of constant values, thereby making changes easier to make, and increasing reliability. Third, and a side effect of the second reason, is that manifest constants isolate implementation or environment specifics when they are represented by constant values.

To further isolate the effects of change, manifest constants and other identifiers can be grouped together into header files allowing you to share identifiers between program (.prg) files, applications, and groups of programmers. Using this methodology, definitions can be standardized for use throughout a development organization. Merge header files into the current program file by using the #include directive.

For examples of header files, refer to the supplied header files in the CLIP53INCLUDE directory.

Compiler Pseudo-functions

In addition to defining constants as values, the #define directive can also define pseudofunctions that are resolved at compile time. A pseudofunction definition is an identifier immediately followed by an argument list, delimited by parentheses, and the replacement expression. For example:

#define AREA(nLength, nWidth) (nLength * nWidth) #define SETVAR(x, y) (x := y) #define Max(x, y) (IF(x > y, x, y))

Pseudofunctions differ from manifest constants by supporting arguments. Whenever the preprocessor scans a source line and encounters a function call that matches the pseudofunction definition, it substitutes the function call with the replacement expression. The arguments of the function call are transported into the replacement expression by the names specified in the argument list of the identifier definition. When the replacement expression is substituted for the pseudofunction, names in the replacement expression are replaced with argument text. For example, the following invocations,

? AREA(10, 12) SETVAR(nValue, 10) ? Max(10, 9)

are replaced by :

? (10 * 12) nValue := 10 ? (IF(10 > 9, 10, 9)

It is important when defining pseudofunctions, that you enclose the result expression in parentheses to enforce the proper order of evaluation. This is particularly important for numeric expressions. In pseudofunctions, you must specify all arguments. If the arguments are not specified, the function call is not expanded as a pseudofunction and exits the preprocessor to the compiler as encountered.

Pseudofunctions do not entail the overhead of a function call and are, therefore, generally faster. They also use less memory. Pseudofunctions, however, are more difficult to debug within the debugger, have a scope different from declared functions and procedures, do not allow skipped arguments, and are case-sensitive.

You can avoid some of these deficiencies by defining a pseudofunction using the #translate directive. #translate pseudofunctions are not case- sensitive, allow optional arguments, and obey the dBASE four-letter rule. See the #translate directive reference in this chapter for more information.

■  In this example a manifest constant conditionally controls the
   compilation of debugging code:

   #define DEBUG
   .
   . <statements>
   .
   #ifdef DEBUG
      Assert(FILE("System.dbf"))
   #endif

■  This example defines a manifest constant and substitutes it
   for an Inkey() value:

   #define K_ESC      27
   .
   . <statements>
   .
   IF Inkey() != K_ESC
      DoIt()
   ELSE
      StopIt()
   ENDIF

■  This example defines pseudofunctions for the standard
   CA-Clipper functions, Max() and AllTrim():

   #define Max(arg1, arg2)      (IF(arg1 > arg2, ;
      arg1, arg2))
   #define AllTrim(cString)   (RTrim(LTrim(cString)))
   .
   . <statements>
   .
   ? Max(1, 2)
   ? AllTrim("  Hello  ")

■  This example displays an error message based on whether or not
   a NETWORK identifier was defined:

   #ifdef NETWORK
      #error Network version not implemented.
   #endif

#ifdef <identifier>
   <statements>...
[#else]
   <statements>...
#endif

#ifdef…#endif lets you perform a conditional compilation. It does this by identifying a section of source code to be compiled if the specified identifier is defined. The identifier can be defined using either the #define directive or the /D compiler option which lets you define an identifier or manifest constant from the compiler command line.

The #else directive specifies the code to compile if identifier is undefined. The #endif terminates the conditional compilation block.

Conditional compilation is particularly useful when maintaining many different versions of the same program. For example, the demo code and full system code could be included in the same program file and controlled by a single #define statement.

■  This code fragment is a general skeleton for conditional
   compilation with #ifdef:

   #define DEMO
   .
   . <statements>
   .
   #ifdef DEMO
      <demo specific statements>
   #endif

■  This example controls conditional compilation with an
   identifier defined on the compiler command line with the /D option.

   In DOS:

   C>CLIPPER Myfile /DDEBUG

   In the program (.prg) file:

   #ifdef DEBUG
      Assert(<some condition>)
   #endif

■  This example defines a manifest constant to one value if it
   does not exist and redefines it to another if it exists:

   #ifdef M_MARGIN
      #undef  M_MARGIN
      #define M_MARGIN   15
   #else
      #define M_MARGIN   10
   #endif

#ifndef <identifier>
   <statements>...
[#else]
   <statements>...
#endif

#ifndef…#endif lets you perform conditional compilation by identifying a section of source code to compile if the specified identifier is undefined.

The #else directive specifies the code to compile if identifier is defined. The #endif terminates the conditional compilation block.

■  This code fragment is a general skeleton for conditional
   compilation with #ifndef:

   #define DEBUG
   .
   . <statements>
   .
   #ifndef DEBUG
      <optimized version of code>
   #else
      <debugging version of code>
   #endif

■  This example compiles a section of code if a specific
   identifier is undefined.

   In DOS:

   C>CLIPPER Myfile

   In the program (.prg) file:

   #ifndef NODEBUG
      Assert(<some condition>)
   #endif

■  This example overrides a default definition in the program
   (.prg) file using a manifest constant defined on the compiler command
   line with the /D option

   In DOS:

   C>CLIPPER Myfile /DM_MARGIN=10

   In the program (.prg) file:

   #ifndef M_MARGIN
      #define M_MARGIN   15
   #endif

#include "<headerFileSpec>"

headerFileSpec specifies the name of another source file to include in the current source file. As indicated in the syntax, the name must be enclosed in double quotation marks.

headerFileSpec may contain an explicit path and file name as well as a file extension. If, however, no path is specified, the preprocessor searches the following places:

■ Source file directory

■ Directories supplied with the /I option

■ Directories specified in the INCLUDE environment variable

#include directives may be nested up to 15 levels deep—that is, a file that has been included may contain #include directives, up to 15 levels.

#include inserts the contents of the specified file in place of the #include directive in the source file. By convention, the file inserted is referred to as a header file. Header files should contain only preprocessor directives and external declarations. By convention CA-Clipper header files have a .ch extension.

When deciding where to locate your header files, you have two basic choices. You can place them in the source file directory where they are local to the current system; or, you can make them globally available by placing them in the directory specified in the INCLUDE environment variable. A list of one or more directories can be specified.

Header files overcome the one major drawback of defining constants or inline functions—the #define directive only affects the file in which it is contained. This means that every program which needs access to these statements must have a list of directives at the top. The solution to this problem is to place #define statements in a separate file and use the #include directive to tell the preprocessor to include that file before compiling.

For example, suppose the file «Inkey.ch» contains a list of #define directives assigning key values to constants. Instead of including these directives at the top of each program file (.prg) requiring access to them, you can simply place the following line at the top of each program file:

#include «Inkey.ch»

This causes the preprocessor to look for inkey.ch and place all the directives contained within it at the top of this program.

Another advantage of using the #include directive is that all the #define statements are contained in one file. If any modifications to these statements are necessary, only the #include file need be altered; the program itself remains untouched.

Note that the scope of definitions within an included header file is the current program file unless the header file is included on the compiler command line with the /U option. In this case, the scope is all the program files compiled in the current invocation of the compiler.

■ Supplied header files: CA-Clipper provides a number of header

files containing manifest constants for common operations. Refer to CLIP53INCLUDE for more information.

■ std.ch—the standard header file: std.ch is the standard

header file provided with CA-Clipper. Its default location is CLIP53INCLUDE. std.ch contains the definitions of all CA-Clipper commands and the standard functions specified as pseudofunctions. It is strongly recommended that no changes be made to std.ch. If changes are desired, it is advisable to copy std.ch to a new name, make the changes, and compile with /U.

This header file differs somewhat from a header file you might #include in that everything defined in std.ch, with #define, #translate, or #command, has a scope of the entire compile rather than the current source file.

■  This example uses #include to insert inkey.ch, a file of
   common keyboard definitions, into a key exception handler called by
   an interface function:

   #include "Inkey.ch"

   FUNCTION GetEvent()
      LOCAL nKey, nResult
      nKey = Inkey(0)
      DO CASE
      CASE nKey = K_F10
         nResult := DoMenu("Browse")
      CASE nKey = K_ESC
         nResult := DoQuit()
         .
         . <statements>
         .
      CASE nKey = K_CTRL_RIGHT
         nResult := DoNextRec()
      ENDCASE
      RETURN nResult

#stdout causes the compiler to output the literal text to the standard output device (stdout) during compilation. If messageText is not specified, a carriage return/line feed pair echoes to stdout.

Warning! Manifest constants are not translated in #stdout. Implementation is identical to #error with the following exceptions: output is written to STDOUT and no compiler error is generated.

This example demonstrates use of #stdout:

#ifdef DEBUG
   #stdout Compiling debugging version...
#endif

PROCEDURE Main()

? "Hello world"
RETURN

#stdout End of "Hello World" program

■  To define and then undefine a manifest constant and a
   pseudofunction:

   #define K_ESC  27
   #define Max(x, y)   IF(x > y, x, y)
   .
   . <statements>
   .
   #undef K_ESC
   #undef MAX

■  To use #undef to undefine an identifier before redefining it:

   #define DEBUG
   .
   . <statements>
   .
   #undef DEBUG
   #define DEBUG   .T.

■  To undefine an identifier if it exists, and otherwise define
   it for later portions of the program file:

   #ifdef TEST
      #undef TEST
   #else
      #define TEST
   #endif

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

matchPattern is the pattern to match in the input text.

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

■ Seeking the modulus of any dividend using a zero as the

divisor causes a runtime error. In versions of CA-Clipper prior to Summer ’87, a modulus operation with a zero divisor returned zero.

■  This example shows modulus results using different operands:

   ?  3 %  0            // Result: Runtime error
   ?  3 % -2            // Result:  1
   ? -3 %  2            // Result: -1
   ? -3 %  0            // Result: Runtime error
   ? -1 %  3            // Result: -1
   ? -2 %  3            // Result: -2
   ?  2 % -3            // Result:  2
   ?  1 % -3            // Result:  1

<nNumber1> + <nNumber2>           (addition)
<dDate>    + <nNumber>            (addition)
<cString1> + <cString2>           (concatenation)

The (+) operator performs a number of different operations depending on the data types of the operands:

■ Unary positive sign (numeric): A numeric expression prefaced

with the plus (+) operator performs no operation on the operand except to enforce a higher level of precedence than other numeric operations (except the unary minus).

■ Binary addition sign (numeric, date): If both operands are

numeric, nNumber2 is added to nNumber1 and the result is returned as a numeric value. If either operand is date data type and the other operand numeric data type, the nNumber is added as days to the dDate and a date value is returned.

■ Concatenation (character, memo): If both operands are

character, cString2 (the right operand) is concatenated to cString1 (the left operand) returning a character string.

■  These examples illustrate the various forms of the + operator:

   // Binary addition (numeric)
   ? 1 + 1                           // Result: 2
   ? 1 + 0                           // Result: 1
   ? 0 + 1                           // Result: 1

   // Binary addition (date)
   ? CToD("12/12/88") + 12         // Result: 12/24/88
   ? 12 + CToD("12/12/88")         // Result: 12/24/88

   // Concatenation (character)
   ? "Hi " + "there"               // Result: Hi there

++<idVar>         (prefix increment)
<idVar>++         (postfix increment)

The increment operator (++) increases the value of its operand by one. This operator adds one to the value of idVar and assigns the new value to idVar.

The ++ operator can appear before or after idVar. Specifying the operator before idVar increments and assigns the value before idVar is used. This is called prefix notation, and it is the most common usage. Specifying the operator after idVar, postfix notation, increments and assigns the value after idVar is used. Stated differently, postfix notation delays the assignment portion of the operation until the rest of the expression is evaluated, and prefix notation gives the assignment precedence over all other operations in the expression.

If the reference to idVar is ambiguous (i.e., not declared at compile time and not explicitly qualified with an alias), idVar is always assumed to be MEMVAR. You can assign field variables by declaring the field variable name in a FIELD statement or referring to the field name prefaced by the FIELD-> alias or the name of the work area.

■  This code uses the prefix increment operator in an assignment
   statement.  Therefore, both variables have the same value when
   queried:

   nValue := 0
   nNewValue := ++nValue
   ? nNewValue               // Result:   1
   ? nValue                  // Result:   1

■  In this example, the postfix increment operator increases the
   first operand of the multiplication operation by one, making its
   value 11; however, the assignment of this new value to the nValue
   variable will not take place until the entire expression is
   evaluated.  Therefore, its value is still 10 when the multiplication
   operation occurs, and the result of 11 * 10 is 110.  Finally, when
   nValue is queried again after the expression is evaluated, the
   postfix increment assignment is reflected in its new value, 11.

   nValue := 10
   ? nValue++ * nValue       // Result: 110
   ? nValue                  // Result:  11

AAdd(<aTarget>, <expValue>) → Value

aTarget is the array to which a new element is to be added.

expValue is the value assigned to the new element.

AAdd() is an array function that increases the actual length of the target array by one. The newly created array element is assigned the value specified by expValue.

AAdd() is used to dynamically grow an array. It is useful for building dynamic lists or queues. A good example of this is the GetList array used by the Get system to hold Get objects. After a READ or CLEAR GETS, GetList becomes an empty array. Each time you execute an @...GET command, the Get system uses AAdd() to add a new element to the end of the GetList array, and then assigns a new Get object to the new element.

AAdd() is similar to ASize() but only adds one element at a time; ASize() can grow or shrink an array to a specified size. AAdd(), however, has the advantage that it can assign a value to the new element, while ASize() cannot. AAdd() may also seem similar to AIns(), but they are different: AIns() moves elements within an array, but it does not change the array’s length.

Note: If expValue is another array, the new element in the target array will contain a reference to the array specified by expValue.

■  These examples demonstrate the effects of multiple invocations
   of AAdd() to an array:

   aArray := {}                  // Result: aArray is an empty array
   AAdd(aArray, 5)               // Result: aArray is { 5 }
   AAdd(aArray, 10)              // Result: aArray is { 5, 10 }
   AAdd(aArray, { 12, 10 })      // Result: aArray is
                                 // { 5, 10, { 12, 10 } }

Abs() is a numeric function that determines the magnitude of a numeric value independent of its sign. It lets you, for example, obtain the difference between two numbers as a positive value without knowing in advance which of the two is larger.

As a formalism, Abs(x) is defined in terms of its argument, x, as follows: if x >= 0, Abs(x) returns x; otherwise, Abs(x) returns the negation of x.

■  These examples show typical results from Abs():

   nNum1 := 100
   nNum2 := 150
   ? nNum1 - nNum2                  // Result: -50
   ? Abs(nNum1 - nNum2)             // Result: 50
   ? Abs(nNum2 - nNum1)             // Result: 50
   ? Abs(-12)                       // Result: 12
   ? Abs(0)                         // Result: 0

ACCEPT [<expPrompt>] TO <idVar>

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

idVar is the variable that will hold input from the keyboard. If the specified idVar does not exist or is not visible, a private variable is created.

ACCEPT is a console command and wait state that takes input from the keyboard and assigns it as a character string to the specified variable. When ACCEPT is executed, it first performs a carriage return/linefeed, displays the prompt, and then begins taking characters from the keyboard at the first character position following the prompt. You may input up to 255 characters. When input reaches the edge of the screen, as defined by MaxCol(), the cursor moves to the next line.

ACCEPT supports only two editing 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 ACCEPT. If Return is the only key pressed, ACCEPT assigns a null value («») to idVar.

■  This example uses ACCEPT to get keyboard input from the user:

   LOCAL cVar
   ACCEPT "Enter a value: " TO cVar
   IF cVar == ""
      ? "User pressed Return"
   ELSE
      ? "User input:", cVar
   ENDIF

AChoice(<nTop>, <nLeft>, <nBottom>, <nRight>,
   <acMenuItems>,
   [<alSelectableItems> | <lSelectableItems>],
   [<cUserFunction>],
   [<nInitialItem>],
   [<nWindowRow>]) → nPosition

nTop, nLeft and nBottom, nRight are the upper- left and lower-right window coordinates. Row values can range from zero to MaxRow() and column values can range from zero to MaxCol().

acMenuItems is an array of character strings to display as the menu items. The individual menu items are later identified by their numeric positions in this array.

alSelectableItems is a parallel array of logical values—one element for each item in acMenuItems—that specify the selectable menu items. Elements can be logical values or character strings. AChoice() will not permit a null string and stops displaying if it encounters one. If the element is a character string, it is evaluated as a macro expression which should evaluate to a logical data type. In either case, a value of false (.F.) means that the corresponding menu item is not available, and a value of true (.T.) means that it is available. If you specify lSelectableItems instead of an array, false (.F.) makes all menu items unavailable and true (.T.) makes all menu items available. By default, all menu items are available for selection.

cUserFunction is the name of a user-defined function that executes when an unrecognizable key is pressed. Specify the function name as a character expression without parentheses or arguments. Note that the behavior of AChoice() is affected by the presence of this argument. Refer to the discussion below for further information.

nInitialItem is the position in the acMenuItems array of the item that will be highlighted when the menu is initially displayed. If you specify an unavailable menu item or no argument at all, the initial menu item is the first selectable item in the array.

nWindowRow is the number of the window row on which the initial menu item will appear. Row numbering begins with zero. By default, the initial menu item appears as close to the top of the window as possible, without leaving any empty rows at the bottom. Thus, if there are enough menu items following the initial one to fill up the window, the initial form will appear on the first row (row zero) of the menu. This function argument is used to control the initial menu appearance when there are more menu items than will fit in the window.

As with all functions, optional arguments are omitted by using a comma instead of the actual argument.

AChoice() is a user interface function that can create various kinds of pop-up menus. Each menu uses an array of character strings as menu items and a parallel array of logical values to determine whether items are selectable. When you invoke AChoice(), the list of menu items is displayed within the specified window coordinates. When the user presses Return, the current item is selected, and AChoice() returns the position of the menu item in acMenuItems. When the user presses Esc, AChoice() aborts and returns zero.

The menu items scroll if the number of items in acMenuItems exceeds the number of rows in the menu window, and the user attempts to move the highlight beyond the top or bottom of the menu window. Note that the highlight does not wrap when you reach the top or bottom of the list of items. Pressing the first letter does, however, wrap the highlight within the set of items whose first letter matches the key you press.

■ Navigating the menu: AChoice() has two modes depending on

whether the cUserFunction argument is specified. If it is not specified the following navigation keys are active:

AChoice() Keys (No User Function)

■ Color: Menu items are displayed in standard color, the

highlight in enhanced color, and the unavailable items in the unselected color. For example, the following color statement

SetColor(«W+/N, BG+/B, , , W/N»)

displays a menu that is bright white on black, the highlight is bright cyan on blue, and the unavailable menu items are dim white on black.

■ User function: Like the other user interface functions,

AChoice() supports a user function. The user function is specified when you want to nest AChoice() invocations to create hierarchical menus or to redefine keys.

When a user function is specified, AChoice() processes only a limited set of keys automatically. These are listed in the following table. All other keys generate a key exception which passes control to the user function for handling. Control is also passed to the user function when AChoice() goes idle (i.e., when there are no more keys to process).

AChoice() Keys (User Function Specified)

When AChoice() executes the user function, it automatically passes the following three parameters:

— The current AChoice() mode

— The current element in the array of items

— The relative row position within the menu window

The mode indicates the current state of AChoice() depending on the key pressed and the action taken by AChoice() prior to executing the user function. The mode parameter has the following possible values:

AChoice() Modes

After the user function has performed whatever operations are appropriate to the AChoice() mode or LastKey(), it must RETURN a value requesting AChoice() to perform an operation from the following set of actions:

AChoice() User Function Return Values

■  This example uses two literal arrays to specify the menu items
   and selection criteria.  After the menu is displayed and the user
   makes a selection, the name of the selected menu item is displayed:

   acMenuItems := {"One", "Two", "-------", "Three"}
   alSelectableItems := {.T., .T., .F., .T.}
   nPosition := AChoice(10, 10, 12, 15, acMenuItems,;
                            alSelectableItems)
   ? acMenuItems[nPosition]

■  This example declares an array of menu items and supplies a
   user-defined function which displays a message with each highlighted
   choice:

   #include "achoice.ch"
   #include "inkey.ch"

   PROCEDURE Main()

      LOCAL acMenuItems[4], cUserFunction, nRetVal
      LOCAL nKey, nPos

      acMenuItems[1] := "Add"
      acMenuItems[2] := "Edit"
      acMenuItems[3] := "Delete"
      acMenuItems[4] := "Update"

      CLS

      nPos := AChoice( 10, 10, 13, 15, acMenuItems,;
                     .T., "cUserFunction" )
      DO CASE
      CASE nPos == 1
         //  Put ADD routine here
      CASE nPos == 2
         //  Put EDIT routine here
      CASE nPos == 3
         //  Put DELETE routine here
      CASE nPos ==4
         //  Put UPDATE routine here
      ENDCASE

   RETURN


   FUNCTION cUserFunction( nMode, nCurElement, nRowPos )

      LOCAL nRetVal := AC_CONT     // Default, Continue
      LOCAL nKey := LastKey()

      DO CASE
   // After all pending keys are processed, display message
      CASE nMode == AC_IDLE
      DO CASE
         CASE nCurElement == 1
            @ 22, 5 SAY " Adding   "
         CASE nCurElement == 2
            @ 22, 5 SAY " Editing  "
         CASE nCurElement ==  3
            @ 22, 5 SAY " Deleting "
         CASE nCurElement ==  4
            @ 22, 5 SAY " Updating "
      ENDCASE

         nRetVal := AC_CONT            // Continue AChoice()

      CASE nMode == AC_HITTOP          // Attempt to go past Top
         Tone( 100, 3 )
      CASE nMode == AC_HITBOTTOM       // Attempt to go past
                                       // Bottom
         Tone( 100, 3 )

      CASE nMode == AC_EXCEPT          // Key Exception
         DO CASE
         CASE nKey == K_RETURN         // If RETURN key, select
            nRetVal := AC_SELECT
         CASE nKey == K_ESC            // If ESCAPE key, abort
            nRetVal := AC_ABORT
         OTHERWISE
               nRetVal := AC_GOTO      // Otherwise, go to item
         ENDCASE
      ENDCASE

   RETURN nRetVal

■  The next example declares the arrays, specifies a selection
   condition for one of the menu items, and supplies a user function:

   EXTERNAL Updated
   //
   FUNCTION MyMenu
      LOCAL acMenuItems[4], alSelectableItems[4],;
             cUserFunction := "DoIt"
      //
      acMenuItems[1] := "Add Record"
      acMenuItems[2] := "Edit Record"
      acMenuItems[3] := "Delete Record"
      acMenuItems[4] := "Update Record"
      //
      alSelectableItems[1] := .T.
      alSelectableItems[2] := .T.
      alSelectableItems[3] := .T.
      alSelectableItems[4] := "!Updated()"
      // Selection condition

      RETURN AChoice(10, 10, 12, 15, acMenuItems,;
         alSelectableItems, cUserFunction)

■  This example uses two arrays to specify menu items and
   corresponding action blocks.  After the menu is displayed and the
   user makes a selection, the AChoice() return value is used to
   determine which action block of the aActionItems array is evaluated:

   PROCEDURE Main()
      LOCAL nChoice
      LOCAL aMenuItems := { "Add Record   ", ;
                               "Edit Record  ", ;
                               "Delete Record", ;
                               "Update Record"   }

      LOCAL aActionItems := { {|| AddFunc()  }, ;
                               {|| EditFunc() }, ;
                               {|| DelFunc()  }, ;
                               {|| UpdFunc()  }  }

      nChoice := AChoice( 10, 10, 13, 22, aMenuItems )

      IF nChoice == 0
         QUIT      // ESCAPE was pressed
      ENDIF

      Eval( aActionItems[nChoice] )

   RETURN

AClone(<aSource>) → aDuplicate

■  This example creates an array then duplicates it using
   AClone().  The first array is then altered, but the duplicate copy is
   unaffected:

   LOCAL aOne, aTwo
   aOne := { 1, 2, 3 }         // Result: aOne is {1, 2, 3}
   aTwo := AClone(aOne)        // Result: aTwo is {1, 2, 3}
   aOne[1] := 99               // Result: aOne is {99, 2, 3}
                              // aTwo is still {1, 2, 3}

ACopy(<aSource>, <aTarget>,
   [<nStart>], [<nCount>], [<nTargetPos>]) → aTarget

aSource is the array to copy elements from.

aTarget is the array to copy elements to.

nStart is the starting element position in the aSource array. If not specified, the default value is one.

nCount is the number of elements to copy from the aSource array beginning at the nStart position. If nCount is not specified, all elements in aSource beginning with the starting element are copied.

nTargetPos is the starting element position in the aTarget array to receive elements from aSource. If not specified, the default value is one.

ACopy() is an array function that copies elements from the aSource array to the aTarget array. The aTarget array must already exist and be large enough to hold the copied elements. If the aSource array has more elements, some elements will not be copied.

ACopy() copies values of all data types including NIL and code blocks. If an element of the aSource array is a subarray, the corresponding element in the aTarget array will contain a reference to the subarray. Thus, ACopy() will not create a complete duplicate of a multidimensional array. To do this, use the AClone() function.

■  This example creates two arrays, each filled with a value.
   The first two elements from the source array are then copied into the
   target array:

   LOCAL nCount := 2, nStart := 1, aOne, aTwo
   aOne := { 1, 1, 1 }
   aTwo := { 2, 2, 2 }
   ACopy(aOne, aTwo, nStart, nCount)
   // Result: aTwo is now { 1, 1, 2 }

ADel(<aTarget>, <nPosition>) → aTarget

aTarget is the array to delete an element from.

nPosition is the position of the target array element to be deleted.

ADel() is an array function that deletes an element from an array. The contents of the specified array element is lost, and all elements from that position to the end of the array are shifted up one element. The last element in the array becomes NIL.

Warning! CA-Clipper implements multidimensional arrays by nesting arrays within other arrays. If the aTarget array is a multidimensional array, ADel() can delete an entire subarray specified by nPosition, causing aTarget to describe an array with a different structure than the original.

■  This example creates a constant array of three elements, and
   then deletes the second element.  The third element is moved up one
   position, and the new third element is assigned a NIL:

   LOCAL aArray
   aArray := { 1, 2, 3 }      // Result: aArray is
                              // now { 1, 2, 3 }
   ADel(aArray, 2)            // Result: aArray is
                              // now { 1, 3, NIL }

ADir([<cFilespec>],
   [<aFilenames>],
   [<aSizes>],
   [<aDates>],
   [<aTimes>],
   [<aAttributes>]) → nFiles

cFilespec is the path specification of files to include in the scan of the DEFAULT directory. It is a standard file specification that can include the wildcard characters * and ?, as well as a drive and path reference. If omitted, the default specification is *.*.

aFilenames is the array to fill with the file names matching cFilespec. Each element contains the file name and extension as a character string in all uppercase letters.

aSizes is the array to fill with the sizes of the corresponding files in the aFilenames array. Each element is a numeric data type.

aDates is the array to fill with the dates of the corresponding files in the aFilenames array. Each element is a date data type.

aTimes is the array to fill with the times of the corresponding files in the aFilenames array. Each element filled contains a character string of the form: hh:mm:ss.

aAttributes is the array to fill with attributes of the corresponding files in the aFilenames array. Each element is a character string. If aAttributes is specified, hidden, system, and directory files are included as well as normal files. If aAttributes is not specified, only normal files are included.

ADir() is an array function that performs two basic operations. First, it returns the number of files matching the file specification. Second, it fills a series of arrays with file names, sizes, dates, times, and attributes.

ADir() is a compatibility function and therefore not recommended. It is superseded by the Directory() function which returns all file information in a multidimensional array.

■ Directories: If you specify the aAttributes argument and

cFilespec is *.*, directories will be included in aFilenames. In the aAttributes array, directories are indicated with an attribute value of «D». If ADir() is executed within a subdirectory, the first two entries of the aFilenames array are «.» and «..», the parent and current directory aliases. The date and time of last update are reported for directories, but the size of a directory is always zero.

■  This example creates an array to hold the names of all .txt
   files in the current DEFAULT directory, then uses AEval() to list
   them to the console:

   LOCAL aFiles[ADir("*.TXT")]
   ADir("*.TXT", aFiles)
   AEval(aFiles, { |element| QOut(element) })

AEval(<aArray>, <bBlock>,
   [<nStart>], [<nCount>]) → aArray

aArray is the array to traverse.

bBlock is a code block to execute for each element encountered.

nStart is the starting element. If not specified, the default is element one.

nCount is the number of elements to process from nStart. If not specified, the default is all elements to the end of the array.

AEval() is an array function that evaluates a code block once for each element of an array, passing the element value and the element index as block parameters. The return value of the block is ignored. All elements in aArray are processed unless either the nStart or the nCount argument is specified.

AEval() makes no assumptions about the contents of the array elements it is passing to the block. It is assumed that the supplied block knows what type of data will be in each element.

AEval() is similar to dbEval() which applies a block to each record of a database file. Like dbEval(), AEval() can be used as a primitive for the construction of iteration commands for both simple and complex array structures.

Refer to the Code Blocks section in the «Basic Concepts» chapter of the Programming and Utilities Guide for more information on the theory and syntax of code blocks.

■  This example uses AEval() to display an array of file names
   and file sizes returned from the Directory() function:

   #include "Directry.ch"
   //
   LOCAL aFiles := Directory("*.dbf"), nTotal := 0
   AEval(aFiles,;
      { | aDbfFile |;
         QOut(PadR(aDbfFile[F_NAME], 10), aDbfFile[F_SIZE]),;
         nTotal += aDbfFile[F_SIZE]);
      } )
   //
   ?
   ? "Total Bytes:", nTotal

■  This example uses AEval() to build a list consisting of
   selected items from a multidimensional array:

   #include "Directry.ch"
   //
   LOCAL aFiles := Directory("*.dbf"), aNames := {}
   AEval(aFiles,;
      { | file | AAdd(aNames, file[F_NAME]) };
      )

■  This example changes the contents of the array element
   depending on a condition.  Notice the use of the codeblock
   parameters:

   LOCAL aArray[6]
   AFill(aArray,"old")
   AEval(aArray,;
   {|cValue,nIndex| IF(cValue == "old",;
                     aArray[nIndex] := "new",)})

AFields([<aFieldNames>], [<aTypes>],
   [<aWidths>], [<aDecimals>]) → nFields

aFieldNames is the array to fill with field names. Each element is a character string.

aTypes is the array to fill with the type of fields in aFieldNames. Each element is a character string.

aWidths is the array to fill with the widths of fields in aFieldNames. Each element is numeric data type.

aDecimals is the array to fill with the number of decimals defined for fields in aFieldNames. Each element is numeric data type. If the field type is not numeric, the aDecimals element is zero.

AFields() is an array function that fills a series of arrays (structure attribute arrays) with the structure of the database file currently open, one element in each array per field. AFields() works like ADir(), filling a series of existing arrays with information. To use AFields(), you must first create the arrays to hold the database structure information, each with the same number of elements as the number of fields (i.e. FCount()). Once the structure attribute arrays are created, you can then invoke AFields() to fill the structure arrays with information about each field.

By default, AFields() operates on the currently selected work area. It can operate on an unselected work area if you specify it within an aliased expression (see example below).

AFields() is a compatibility function and therefore is not recommended. It is superseded by dbStruct(), which does not require the existence of any arrays prior to invocation and returns a multidimensional array containing the current database file structure.

■  This example demonstrates how AFields() and AChoice() can be
   used together to create a fields picklist:

   USE Sales NEW
   PRIVATE aFieldNames[FCount()]
   AFields(aFieldNames)
   @ 1, 0 TO 10, 10 DOUBLE
   nChoice := AChoice(2, 1, 9, 9, aFieldNames)
   @ 12, 0 SAY IF(nChoice != 0, aFieldNames[nChoice],;
                   "None selected")
   RETURN

■  This example uses AFields() with an aliased expression to fill
   arrays with the structure of Sales.dbf, open in an unselected work
   area:

   LOCAL aFieldNames, aTypes, aWidths, aDecimals
   USE Sales NEW
   USE Customer NEW
   //
   aFieldNames := Sales->(Array(FCount()))
   aTypes := Sales->(Array(FCount()))
   aWidths := Sales->(Array(FCount()))
   aDecimals := Sales->(Array(FCount()))
   //
   Sales->(AFields(aFieldNames, aTypes, ;
            aWidths, aDecimals))

AFill(<aTarget>, <expValue>,
   [<nStart>], [<nCount>]) → aTarget

aTarget is the array to be filled.

expValue is the value to be placed in each array element. It can be an expression of any valid data type.

nStart is the position of the first element to be filled. If this argument is omitted, the default value is one.

nCount is the number of elements to be filled starting with element nStart. If this argument is omitted, elements are filled from the starting element position to the end of the array.

AFill() is an array function that fills the specified array with a single value of any data type (including an array, code block, or NIL) by assigning expValue to each array element in the specified range.

Warning! AFill() cannot be used to fill multidimensional arrays. CA-Clipper implements multidimensional arrays by nesting arrays within other arrays. Using AFill() with a multidimensional array will overwrite subarrays used for the other dimensions of the array.

■  This example, creates a three-element array.  The array is
   then filled with the logical value, (.F.).  Finally, elements in
   positions two and three are assigned the new value of true (.T.):

   LOCAL aLogic[3]
   // Result: aLogic is { NIL, NIL, NIL }

   AFill(aLogic, .F.)
   // Result: aLogic is { .F., .F., .F. }

   AFill(aLogic, .T., 2, 2)
   // Result: aLogic is { .F., .T., .T. }

AIns(<aTarget>, <nPosition>) → aTarget

aTarget is the array into which a new element will be inserted.

nPosition is the position at which the new element will be inserted.

AIns() is an array function that inserts a new element into a specified array. The newly inserted element is NIL data type until a new value is assigned to it. After the insertion, the last element in the array is discarded, and all elements after the new element are shifted down one position.

Warning! AIns() must be used carefully with multidimensional arrays. Multidimensional arrays in CA-Clipper are implemented by nesting arrays within other arrays. Using AIns() in a multidimensional array discards the last element in the specified target array which, if it is an array element, will cause one or more dimensions to be lost. To insert a new dimension into an array, first add a new element to the end of the array using AAdd() or ASize() before using AIns().

■  This example demonstrates the effect of using AIns() on an
   array:

   LOCAL aArray
   aArray := { 1, 2, 3 }      // Result: aArray is
                              // now { 1, 2, 3 }
   AIns(aArray, 2)            // Result: aArray is
                              // now { 1, NIL, 2 }

Alert( <cMessage>, [<aOptions>] ) → nChoice

cMessage is the message text displayed and 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 up to 4 possible responses to the dialog box.

The Alert() function creates a simple modal dialog. It is useful in error handlers and other «pause» functions. The user can respond by moving a highlight bar and pressing the Return or SpaceBar 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 CA-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 (i.e., 80-column, without word wrap, each line ended with carriage return/linefeed).

■  This example demonstrates use of an alert dialog box.  First,
   the array of options is defined, the Alert() function gets 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

Alias([<nWorkArea>]) → cAlias

Alias() is a database function that determines the alias of a specified work area. An alias is the name assigned to a work area when a database file is USEd. The actual name assigned is either the name of the database file, or a name explicitly assigned with the ALIAS clause of the USE command.

Alias() is the inverse of the Select() function. Alias() returns the alias name given the work area number, and Select() returns the work area number given the alias name.

■ This example returns the name of the previously selected work

area:

USE File1 NEW ALIAS Test1 nOldArea := Select() USE File2 NEW ALIAS Test2 ? Alias( nOldArea ) // Returns Test1

AllTrim(<cString>) → cTrimString

■ Space characters: The AllTrim() function treats carriage

returns, line feeds, and tabs as space characters and removes these as well.

■  This 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

nAction defines what action AltD() performs when invoked. The following is a complete list of nAction values and their actions:

AltD() Actions

■  This example demonstrates a series of manifest constants that
   can be used as arguments for AltD() before invoking the debugger
   programmatically:

   #define ALTD_DISABLE      0
   #define ALTD_ENABLE      1
   //
   AltD(ALTD_ENABLE)

ANNOUNCE is a declaration statement that defines a module identifier. A linker may use this identifier later to satisfy pending module REQUESTs. ANNOUNCE and REQUEST provide a mechanism for managing application modules (.prg files).

Specify ANNOUNCE statements prior to any executable statements in a program file. A source (.prg) file can only have one module identifier; all subsequent ANNOUNCE declarations produce a compiler warning and will be ignored. Module identifiers must be unique and should not duplicate the name of any procedures or user-defined functions in a source (.prg) file.

■  This example illustrates the ANNOUNCE declaration:

   ANNOUNCE CustomInit

   INIT PROCEDURE MyInit
      ? "Hypothetical Industries, Inc."
      RETURN

   The above program module, CustomInit, should be compiled with the /N
   option.  Subsequently, the program is addressed in the source code of
   another program module through use of the REQUEST statement,

   REQUEST CustomInit

   which causes the module CustomInit to be linked into the resultant
   executable (.EXE) file.

APPEND BLANK is a database command that adds a new record to the end of the current database file and then makes it the current record. The new field values are initialized to the empty values for each data type: character fields are assigned with spaces; numeric fields are assigned zero; logical fields are assigned false (.F.); date fields are assigned CToD(«»); and memo fields are left empty.

If operating under a network with the current database file shared, APPEND BLANK attempts to add and then lock a new record. If another user has locked the database file with FLock() or locked LastRec() + 1 with RLock(), NetErr() returns true (.T.). Note that a newly APPENDed record remains locked until you lock another record or perform an UNLOCK. APPEND BLANK does not release an FLock() set by the current user.

■  This example attempts to add a record to a shared database
   file and uses NetErr() to test whether the operation succeeded:

   USE Sales SHARED NEW
   .
   . <statements>
   .
   APPEND BLANK
   IF !NetErr()
      <update empty record>...
   ELSE
      ? "Append operation failed"
      BREAK
   ENDIF

APPEND FROM <xcFile>
   [FIELDS <idField list>]
   [<scope>] [WHILE <lCondition>] [FOR <lCondition>]
   [SDF | DELIMITED [WITH BLANK | <xcDelimiter>] |
   [VIA <xcDriver>]]

FROM xcFile specifies the name of the source file. You can specify xcFile either as a literal file name or as a character expression enclosed in parentheses. If a file extension is not specified, .dbf is the default input file type. If SDF or DELIMITED is specified, the file extension is assumed to be .txt unless otherwise specified.

FIELDS idField list specifies the list of fields to copy from xcFile. The default is all fields.

scope is the portion of the source database file to APPEND FROM. NEXT n APPENDs the first n records. RECORD n APPENDs only record number n from xcFile. The default scope is ALL records in xcFile.

WHILE lCondition specifies the set of records meeting the condition from the first record in the source file until the condition fails.

FOR lCondition specifies the conditional set of records to APPEND FROM within the given scope.

SDF identifies a System Data Format ASCII file. Records and fields are fixed length.

DELIMITED identifies an ASCII text file where character fields are enclosed in double quotation marks (the default delimiter). Note that delimiters are not required and CA-Clipper correctly APPENDs character fields not enclosed in them. Fields and records are variable length.

DELIMITED WITH BLANK identifies an ASCII text file in which fields are separated by one space and character fields are not enclosed in delimiters.

DELIMITED WITH xcDelimiter identifies a delimited ASCII text file where character fields are enclosed using the specified delimiter. You can specify xcDelimiter as a literal character or as a character expression enclosed in parentheses.

See the tables below for more information regarding the format specification requirements for ASCII text files that you want to APPEND using these arguments.

VIA xcDriver specifies the replaceable database driver (RDD) to use to import the desired data. cDriver is the 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 omitted, APPEND FROM uses the driver in the current work area. If you specify the VIA clause, you must REQUEST the appropriate RDDs to be linked into the application.

Warning! If the DELIMITED WITH clause is specified on a COPY TO or APPEND FROM command line, it must be the last clause specified.

APPEND FROM adds records to the current database file from an ASCII text file or another database file. Only fields with the same names and types are APPENDed. Fields with the same name from both the current database file and xcFile must be the same data type. If they are not, a runtime error occurs when the APPEND FROM command is invoked.

Any date information in xcFile must be in the format yyyymmdd to be properly APPENDed.

In a network environment, APPEND FROM does not require that the current database file be USEed EXCLUSIVEly or locked with FLock() to perform its operation. As each record is added, CA-Clipper automatically arbitrates contention for the new record.

When you invoke APPEND FROM, CA-Clipper attempts to open xcFile as shared and read-only. If access is denied, APPEND FROM terminates with a runtime error. Refer to the «Network Programming» chapter in the Programming and Utilities Guide for more information. No error is raised if you attempt to open a .dbf file that is already open.

This table shows the format specifications for SDF text files:

SDF Text File Format Specifications

This table shows the format specifications for DELIMITED and DELIMITED WITH xcDelimiter ASCII text files:

DELIMITED Text File Format Specifications

This table shows the format specifications for DELIMITED WITH BLANK ASCII text files:

DELIMITED WITH BLANK Text File Format Specifications

■ Deleted records: If DELETED is OFF, deleted records in

xcFile are APPENDed to the current database file and retain their deleted status. If DELETED is ON, however, none of the deleted xcFile records are APPENDed.

■ Unmatched field widths: If a field in the current database

file is a character type and has a field length greater than the incoming xcFile data, CA-Clipper pads the xcFile data with blanks. If the current field is a character data type and its field length is less than the incoming xcFile data, the xcFile data is truncated to fit. If the current field is a numeric type and the incoming xcFile data has more digits than the current field length, a runtime error occurs.

■  This example demonstrates an APPEND FROM command using a
   fields list and a FOR condition:

   USE Sales NEW
   APPEND FROM BranchFile FIELDS Branch, Salesman, Amount;
      FOR Branch = 100

■  This example demonstrates how a <scope> can be specified to
   import a particular record from another database file:

   APPEND RECORD 5 FROM Temp

Array(<nElements> [, <nElements>...]) aArray

Array() is an array function that returns an uninitialized array with the specified number of elements and dimensions. If more than one nElements argument is specified, a multidimensional array is created with the number of dimensions equal to the number of nElements arguments specified. Any nElements that is itself an array creates a nested array.

In CA-Clipper, there are several ways to create an array. You can declare an array using a declaration statement such as LOCAL or STATIC; you can create an array using a PRIVATE or PUBLIC statement; you can assign a literal array to an existing variable; or you can use the Array() function. Array() has the advantage that it can create arrays within expressions or code blocks.

■  This example creates a one-dimensional array of five elements
   using the Array() function, and then shows the equivalent action by
   assigning a literal array of NIL values:

   aArray := Array(5)
   aArray := { NIL, NIL, NIL, NIL, NIL }

■  This example shows three different statements which create the
   same multidimensional array:

   aArray := Array(3, 2)
   aArray := { {NIL, NIL}, {NIL, NIL}, {NIL, NIL} }
   aArray := { Array(2), Array(2), Array(2) }

■  This example creates a nested, multidimensional array:

   aArray := Array(3, {NIL,NIL})

■  These examples illustrate various results of Asc():

   ? Asc("A")                     // Result: 65
   ? Asc("Apple")                 // Result: 65
   ? Asc("a")                     // Result: 97
   ? Asc("Z") - Asc("A")          // Result: 25
   ? Asc("")                      // Result: 0

AScan(<aTarget>, <expSearch>,
   [<nStart>], [<nCount>]) → nStoppedAt

aTarget is the array to be scanned.

expSearch is either a simple value to scan for, or a code block. If expSearch is a simple value it can be character, date, logical, or numeric type.

nStart is the starting element of the scan. If this argument is not specified, the default starting position is one.

nCount is the number of elements to scan from the starting position. If this argument is not specified, all elements from the starting element to the end of the array are scanned.

AScan() is an array function that scans an array for a specified value and operates like SEEK when searching for a simple value. The expSearch value is compared to the target array element beginning with the leftmost character in the target element and proceeding until there are no more characters left in expSearch. If there is no match, AScan() proceeds to the next element in the array.

Since AScan() uses the equal operator (=) for comparisons, it is sensitive to the status of EXACT. If EXACT is ON, the target array element must be exactly equal to the result of expSearch to match.

If the expSearch argument is a code block, AScan() scans the aTarget array executing the block for each element accessed. As each element is encountered, AScan() passes the element’s value as an argument to the code block, and then performs an Eval() on the block. The scanning operation stops when the code block returns true (.T.), or AScan() reaches the last element in the array.

■  This example demonstrates scanning a three-element array using
   simple values and a code block as search criteria.  The code block
   criteria shows how to perform a case-insensitive search:

   aArray := { "Tom", "Mary", "Sue" }
   ? AScan(aArray, "Mary")               // Result: 2
   ? AScan(aArray, "mary")               // Result: 0
   //
   ? AScan(aArray, { |x| Upper(x) ;
         == "MARY" })                    // Result: 2

■  This example demonstrates scanning for multiple instances of a
   search argument after a match is found:

   LOCAL aArray := { "Tom", "Mary", "Sue",;
                      "Mary" }, nStart := 1
   //
   // Get last array element position
   nAtEnd := Len(aArray)
   DO WHILE (nPos := AScan(aArray, "Mary", ;
                nStart)) > 0
      ? nPos, aArray[nPos]
      //
      // Get new starting position and test
      // boundary condition
      IF (nStart := ++nPos) > nAtEnd
         EXIT
      ENDIF
   ENDDO

■  This example scans a two-dimensional array using a code block.
   Note that the parameter aVal in the code block is an array:

   LOCAL aArr:={}
   CLS
   AAdd(aArr,{"one","two"})
   AAdd(aArr,{"three","four"})
   AAdd(aArr,{"five","six"})
   ? AScan(aArr, {|aVal| aVal[2] == "four"})         // Returns 2

ASize(<aTarget>, <nLength>) → aTarget

aTarget is the array to grow or shrink.

nLength is the new size of the array.

ASize() is an array function that changes the actual length of the aTarget array. The array is shortened or lengthened to match the specified length. If the array is shortened, elements at the end of the array are lost. If the array is lengthened, new elements are added to the end of the array and assigned NIL.

ASize() is similar to AAdd() which adds a single new element to the end of an array and optionally assigns a new value at the same time. Note that ASize() is different from AIns() and ADel(), which do not actually change the array’s length.

Note: ASize() only supports single-dimensional arrays.

■  These examples demonstrate adding new elements and deleting
   existing elements:

   aArray := { 1 }          // Result: aArray is { 1 }
   ASize(aArray, 3)         // Result: aArray is { 1, NIL, NIL }
   ASize(aArray, 1)         // Result: aArray is { 1 }

ASort(<aTarget>, [<nStart>],
   [<nCount>], [<bOrder>]) → aTarget

aTarget is the array to be sorted.

nStart is the first element of the sort. If not specified, the default starting position is one.

nCount is the number of elements to be sorted. If not specified, all elements in the array beginning with the starting element are sorted.

bOrder is an optional code block used to determine sorting order. If not specified, the default order is ascending.

ASort() is an array function that sorts all or part of an array containing elements of a single data type. Data types that can be sorted include character, date, logical, and numeric.

If the bOrder argument is not specified, the default order is ascending. Elements with low values are sorted toward the top of the array (first element), while elements with high values are sorted toward the bottom of the array (last element).

If the bOrder block argument is specified, it is used to determine the sorting order. Each time the block is evaluated, two elements from the target array are passed as block parameters. The block must return true (.T.) if the elements are in sorted order. This facility can be used to create a descending or dictionary order sort. See the examples below.

When sorted, character strings are ordered in ASCII sequence; logical values are sorted with false (.F.) as the low value; date values are sorted chronologically; and numeric values are sorted by magnitude.

■ ASort() is only guaranteed to produce sorted output (as

defined by the block), not to preserve any existing natural order in the process.

■ Because CA-Clipper implements multidimensional arrays by

nesting subarrays within other arrays, ASort() will not directly sort a multidimensional array. To sort a nested array, you must supply a code block which properly handles the subarrays.

■  This example creates an array of five unsorted elements, sorts
   the array in ascending order, then sorts the array in descending
   order using a code block:

   aArray := { 3, 5, 1, 2, 4 }
   ASort(aArray)
   // Result: { 1, 2, 3, 4, 5 }

   ASort(aArray,,, { |x, y| x > y })
   // Result: { 5, 4, 3, 2, 1 }


■  This example sorts an array of character strings in ascending
   order, independent of case.  It does this by using a code block that
   converts the elements to uppercase before they are compared:

   aArray := { "Fred", Kate", "ALVIN", "friend" }
   ASort(aArray,,, { |x, y| Upper(x) < Upper(y) })

■  This example sorts a nested array using the second element of
   each subarray:

   aKids := { {"Mary", 14}, {"Joe", 23}, {"Art", 16} }
   aSortKids := ASort(aKids,,, { |x, y| x[2] < y[2] })

   Result:

   { {"Mary", 14}, {"Art", 16}, {"Joe", 23} }

At(<cSearch>, <cTarget>) → nPosition

cSearch is the character substring to be searched for.

cTarget is the character string to be searched.

■  These examples show typical use of At():

   ? At("a", "abcde")                  // Result: 1
   ? At("bcd", "abcde")                // Result: 2
   ? At("a", "bcde")                   // Result: 0

■  This example splits a character string based on the position
   of a comma within the target string:

   cTarget := "Langtree, Lilly"
   ? SubStr(cTarget, 1, At(",", cTarget) - 1)
   // Result: Langtree

   ? SubStr(cTarget, At(",", cTarget) + 2)
   // Result: Lilly

ATail(<aArray>) → Element

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

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

AVERAGE <nExp list> TO <idVar list>
   [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

nExp list is a list of the numeric values to AVERAGE for each record processed.

TO idVar list identifies a list of receiving variables which will contain the average results. Variables that either do not exist or are not visible are created as private variables. idVar list must contain the same number of elements as nExp list.

scope defines the portion of the current database file to AVERAGE. The default scope is 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 AVERAGE within the given scope.

■  This example averages a single numeric field using a condition
   to select a subset of records from the database file:

   USE Sales NEW
   AVERAGE Amount TO nAvgAmount FOR Branch = "100"

■  This example finds the average date for a range of dates:

   AVERAGE (SaleDate - CToD("00/00/00")) ;
      TO nAvgDays FOR !Empty(SaleDate)
   dAvgDate := CToD("00/00/00") + nAvgDays

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

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.

BEGIN SEQUENCE...END is a control structure 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 that is specified with a return value. This is usually 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 within 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.

For more information on error objects, refer to the Error class in this chapter.

■  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>...

■  This example demonstrates an error handler returning an error
   object 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

■  This example re-executes a SEQUENCE statement block 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

Bin2I(<cSignedInt>) → nNumber

■  This example opens a database file using low-level file
   functions and reads the date of last update (bytes 1-3).  The result
   is the same as with LUpdate():

   #include "Fileio.ch"
   //
   nHandle := FOpen("Sales.dbf", FO_READ)
   //
   // Point to byte 1 in the file
   FSeek(nHandle, 1, FS_SET)
   //
   // Read date of last update
   nYear := Bin2I(FReadStr(nHandle, 1) + Chr(0))
   nMonth := Bin2I(FReadStr(nHandle, 1) + Chr(0))
   nDay := Bin2I(FReadStr(nHandle, 1) + Chr(0))
   //
   ? LTrim(Str(nMonth)), LTrim(Str(nDay)), LTrim(Str(nYear))
   FClose(nHandle)

Bin2L(<cSignedInt>) → nNumber

■  This example opens a database file using low-level file
   functions and reads the number of records (bytes 4-7).  The result is
   the same as with LastRec():

   #include "Fileio.ch"
   //
   nHandle := FOpen("Sales.dbf", FO_READ)
   // Note:  Sales.dbf contains 84 records
   //
   // Point to byte 4
   FSeek(nHandle, 4, FS_SET)
   //
   // Read the number of records
   cRecords := Space(4)
   FRead(nHandle, @cRecords, 4)
   //
   ? LTrim(Str(Bin2L(cRecords)))         // Result: 84
   FClose(nHandle)

Bin2W(<cUnsignedInt>) → nNumber

■  This example opens a database file using low-level file
   functions and reads the number of bytes per record (bytes 10-11).
   The result is the same as with RecSize():

   #include "Fileio.ch"
   //
   nHandle := FOpen("Sales.dbf", FO_READ)
   // Note:  The length of a record in Sales.dbf is 124
   //
   // Point to byte 10, the first record size byte
   FSeek(nHandle, 10, FS_SET)
   //
   // Read record size
   cRecSize := Space(2)
   FRead(nHandle, @cRecSize, 2)
   //
   ? LTrim(Str(Bin2W(cRecSize)))            // Result: 124
   FClose(nHandle)

BLOBDirectExport(<nPointer>, <cTargetFile>, [<nMode>])
   → lSuccess

nPointer is a pointer to the BLOB data. This pointer can be obtained using BLOBDIRECTPUT(), BLOBDIRECTEXPORT(), or dbFieldInfo(DBS_BLOB_POINTER, nFieldPos).

cTargetFile is the name of the target file where the BLOB data will be written, including an optional drive, directory, and extension. See SETDEFAULT() and SETPATH() for file searching and creation rules. No default extension is assumed.

If cTargetFile does not exist, it is created. If it exists, this function attempts to open the file in exclusive mode and, if successful, the file is written to without warning or error. If access is denied because another process is using the file, for example, NetErr() is set to true (.T.). Concurrency control:and BLOBDIRECTEXPORT()

nMode is a constant defining the copy mode, as shown in the table below:

Copy Mode Constants

■  This example extracts an array of pointers from the BLOB
   file's root area, then uses one of the pointers to export a picture
   to a file:

   FUNCTION PUTPIX()
      LOCAL cPixFile
      LOCAL nPointer
      LOCAL aBLOBPtrs


      cPixFile := "picture.gif"

      // Customer database with a picture of
      // each customer stored in a field called Pix
      USE Customer NEW VIA "DBFCDX"

      // Assumes that the program previously
      // stored an array of direct BLOB pointers
      // into the root area of the BLOB file.
      // The picture that we want is assumed to
      // be the second array element.
      aBLOBPtrs := BLOBROOTGET()
      nPointer := aBLOBPtrs[2]

      // Export picture pointed to by nPointer to a file
      IF !BLOBDirectExport(nPointer, cPixFile, ;
         BLOB_EXPORT_OVERWRITE)
            Alert("Export of picture " + cPixFile + ";
               failed!")
      ELSE
         // Code for displaying picture would go here
      ENDIF

BLOBDIRECTGET(<nPointer>,   [<nStart>],   [<nCount>])
    → expBLOB

nPointer is a pointer to the BLOB data. This pointer can be obtained using BLOBDIRECTPUT(), BLOBDIRECTIMPORT(), or dbFieldInfo(DBS_BLOB_POINTER, nFieldPos).

nStart is the starting position in nPointer. If nStart is positive, the starting position is relative to the leftmost character in nPointer. If nStart is negative, it is relative to the rightmost character in nPointer. If nStart is omitted, it is assumed to be 1.

nCount is the number of bytes of data to retrieve beginning at nStart. If nCount is larger than the amount of data stored, excess data is ignored. If omitted, BLOBDIRECTGET() retrieves to the end of the data.

Note: nStart and nCount apply to string data only. They are ignored for any other data types.

BLOBDIRECTGET() retrieves data stored in a BLOB file without the need to reference a particular field in the database file. It is particularly useful when accessing data that is larger than 64 KB (such as memo fields created with the BLOBIMPORT() function).

By default, this function 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.

■  This example illustrates storing setup information in a BLOB
   file, then selectively retrieving the stored information:

   FUNCTION PutSettings(aColors,;
                  aPaths, ;
                  aPassWords)

      LOCAL aSettings

      RDDSETDEFAULT ( "DBFCDX" )
      MEMOSETSUPER ( "DBFCDX" )

      USE Setup NEW via "DBFMEMO"

      aSettings := {}
      AAdd(aSettings, BLOBDIRECTPUT(0, aColors))
      AAdd(aSettings, BLOBDIRECTPUT(0, aPaths))
      AAdd(aSettings, BLOBDIRECTPUT(0, aPassWords))

      BLOBROOTPUT(aSettings)

      CLOSE

   FUNCTION GETCOLORS()
      LOCAL aSettings
      LOCAL aColors

      USE Setup NEW VIA "DBFMEMO"

      aSettings := BLOBROOTGET()
      aColors := BLOBDIRECTGET(aSettings[1])

      CLOSE


      RETURN aColors

BLOBDIRECTIMPORT(<nOldPointer>, <cSourceFile>)
    → nNewPointer

nOldPointer is a pointer to the BLOB data which will be released after the import. This pointer can be obtained using BLOBDIRECTPUT(), BLOBDIRECTIMPORT(), or dbFieldInfo(DBS_BLOB_POINTER, nFieldPos). Passing zero (0) disables the release of data.

Important! If specified, BLOBDIRECTIMPORT() releases the space associated with nOldPointer for reuse by other data. Therefore, it is illegal to use nOldPointer with any of the BLOB functions after passing it as an argument to this function. Use the function’s return value to refer to the newly stored data.

cSourceFile is the name of the file from which to read the BLOB data, including an optional drive, directory, and extension. See SETDEFAULT() and SETPATH() for file searching and creation rules. No default extension is assumed.

This function attempts to open cSourceFile in shared mode. If the file does not exist, a runtime error is raised. If the file is successfully opened, the operation proceeds. If access is denied because another process has exclusive use of the file, for example, NetErr() is set to true (.T.). Concurrency control:and BLOBDIRECTIMPORT()

Note: There are no restrictions on the size of cSourceFile except that you must have enough disk space to make the copy.

BLOBDIRECTIMPORT() provides a mechanism for copying the contents of a file into a BLOB file. By default, this function 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.

BLOBDIRECTIMPORT() is used in conjunction with BLOBDIRECTEXPORT() to transfer data back and forth between external files and BLOB files. You can use BLOBDIRECTIMPORT() with a variety of file types, including graphic images, word processor files, and printer fonts. These two functions are excellent for creating databases for documents, graphics, sounds, etc.

Important! After importing a file with BLOBDIRECTIMPORT(), nNewPointer, the return value, is the only way to access the data from the BLOB file. It is up to you to provide permanent storage for this reference (see example below).

Note: dbFieldInfo(DBS_BLOB_TYPE, nFieldPos) will return «C» (string) for any memo field created using BLOBDIRECTIMPORT().

■  This example imports a bitmap (.bmp) file to be part of an
   array of startup data.  The data, stored in the root area of the BLOB
   file, could then be used to display the application's startup screen:

   FUNCTION PUTPIX()
      LOCAL cBMPFile
      LOCAL aSettings

      cBMPFile := "logo.bmp"
      aSettings := {}

      // Customer database where startup parameters
      // are stored for convenience
      USE Customer NEW VIA "DBFMEMO"

      // Get default path settings
      AAdd(aSettings, STARTPATHS())

      // Get default color settings
      AAdd(aSettings, DEFAULTCOLORS())

      // Get company logo for display at startup.
      // There is nothing to free because this
      // is the first time importing.
      nPointer := BLOBDIRECTIMPORT(0, cBMPFile)
      AAdd(aSettings, nPointer)

      // Store the settings in the root area of
      // the customer.fpt file

      BLOBROOTPUT(aSettings)

BLOBDIRECTPUT(<nOldPointer>, <uBLOB>) → nNewPointer

nOldPointer is a reference to previously stored BLOB data. This reference can be obtained using BLOBDIRECTPUT(), BLOBDIRECTIMPORT(), or dbFieldInfo(DBS_BLOB_POINTER, nFieldPos). If other than zero (0), the data referenced by nOldPointer is replaced by uBLOB; otherwise, uBLOB is added to the current contents of the BLOB file.

Important! If specified, BLOBDIRECTPUT() releases the space associated with nOldPointer for reuse by other data. Therefore, it is illegal to use nOldPointer with any of the BLOB functions after passing it as an argument to this function. Use the function’s return value to refer to the newly stored data.

uBLOB is the data you want to put into the BLOB file. uBLOB can be any CA-Clipper data type except code block or an object.

BLOBDIRECTPUT() stores variable length BLOB data without creating a link with a particular memo field in a database file. After adding data to a BLOB file using BLOBDIRECTPUT(), you should store the function’s return value, as this is the only way to access the data from the BLOB file. It is up to you, the developer, to provide permanent storage for this reference (see BLOBROOTPUT()).

By default, this function 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.

■  This example illustrates storing setup information in a BLOB
   file, then selectively retrieving the stored information:

   FUNCTION PutSettings(aColors,;
      aPaths, aPassWords)

      LOCAL aSettings

      USE Setup NEW VIA "DBFMEMO"

      aSettings := {}
      AAdd(aSettings, BLOBDIRECTPUT(0, aColors))

      AAdd(aSettings, BLOBDIRECTPUT(0, aPaths))
      AAdd(aSettings, BLOBDIRECTPUT(0, aPassWords))

      BLOBROOTPUT(aSettings)

      CLOSE

   FUNCTION GETCOLORS()
      LOCAL aSettings
      LOCAL aColors

      USE Setup NEW VIA "DBFMEMO"

      aSettings := BLOBROOTGET()
      aColors := BLOBDIRECTGET(aSettings[1])

      CLOSE

      RETURN aColors

BLOBEXPORT(<nFieldPos>, <cTargetFile>, [<nMode>])
    → lSuccess

nFieldPos is the position of the field in the database file structure.

cTargetFile is the name of the target file where the BLOB data will be written, including an optional drive, directory, and extension. See SETDEFAULT() and SETPATH() for file searching and creation rules. No default extension is assumed.

If cTargetFile does not exist, it is created. If it exists, this function attempts to open the file in exclusive mode and, if successful, the file is written to without warning or error. If access is denied because another process is using the file, for example, NetErr() is set to true (.T.). Concurrency control:and BLOBEXPORT()

nMode is a constant defining the copy mode, as shown in the table below:

Field Information Type Constants

■  This example exports the contents of a field that stores a
   picture to a graphic interchange format (.gif) file, so that the file
   can be programmatically displayed:

   FUNCTION SHOWPIX()
      LOCAL cPixFile := "Picture.gif"
      LOCAL nPos

      // Customer database with a picture of each
      // customer stored in a field called Pix
      USE Customer NEW VIA "DBFCDX"
      nPos := FieldPos("Pix")

      // Export the BLOB file's data
      // for the current Pix field
      IF !BLOBEXPORT(nPos, cPixFile,;
         BLOB_EXPORT_OVERWRITE)
            Alert("Export of picture " + cPixFile + ";
               failed!")
      ELSE
         // Code for displaying picture would go here
      ENDIF

BLOBGet(<nFieldPos>, [<nStart>], [<nCount>]) → uBLOB

nFieldPos is the position of the field in the database file structure.

nStart is the starting position in the memo field of the BLOB data. If nStart is positive, the starting position is relative to the leftmost character in nFieldPos. If nStart is negative, it is relative to the rightmost character in nFieldPos. If nStart is omitted, it is assumed to be 1.

nCount is the number of bytes of data to retrieve beginning at nStart. If nCount is larger than the amount of data stored, excess data is ignored. If omitted, BLOBGET() retrieves to the end of the data.

Note: nStart and nCount apply to string data only. They are ignored for any other data types.

BLOBGET() is very similar to FieldGet(). However, because string type variables cannot be larger than 64 KB, FieldGet() will raise a runtime error when attempting to retrieve memo fields of this magnitude or greater.

BLOBGET() will also raise an error if you attempt to retrieve a field greater than this magnitude; however, you can retrieve any subset of the BLOB data by using an nCount less than 64 KB.

Note: BLOB data less than 64 KB can be retrieved from a memo field using standard means (for example, referring to the field by name in an expression or using the FieldGet() function).

By default, this function 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.

■  This example imports information from a word processing
   document into a field, then uses BLOBGET() to extract the first 25
   characters of the field:

   FUNCTION GETFIRST25()
      LOCAL nPos
      LOCAL cStr

      USE customer NEW VIA "DBFCDX"

      // Field that contains word processor
      // documentation
      nPos := FieldPos("WP_DOC")

      // Import a file (can be larger than 64 KB), then
      // obtain the first 25 characters to show to the
      // user
      IF BLOBImport(nPos, "c:applicationtemp.doc")
         cStr := BLOBGet(nPos, 1, 25)
      ELSE
         cStr := "Error: could not import file!"
      ENDIF

   CLOSE

   RETURN cStr

BLOBImport(<nFieldPos>, <cSourceFile>) → lSuccess

nFieldPos is the position of the field in the database file structure.

cSourceFile is the name of the file from which to read the BLOB data, including an optional drive, directory, and extension. See SETDEFAULT() and SETPATH() for file searching and creation rules. No default extension is assumed.

This function attempts to open cSourceFile in shared mode. If the file does not exist, a runtime error is raised. If the file is successfully opened, the operation proceeds. If access is denied because another process has exclusive use of the file, for example, NetErr() is set to true (.T.). Concurrency control:and BLOBIMPORT()

Note: There are no restrictions on the size of cSourceFile except that you must have enough disk space to make the copy.

BLOBIMPORT() provides a mechanism for copying the contents of a file into a memo field as BLOB data. By default, this function 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.

BLOBIMPORT() is used in conjunction with BLOBEXPORT() to transfer BLOB data back and forth between files and memo fields. You can use BLOBIMPORT() with a variety of file types, including graphic images, word processor files, and printer fonts. These two functions are excellent for creating databases for documents, graphics, sounds, etc.

Note: dbFieldInfo(DBS_BLOB_TYPE, nFieldPos) will return «C» (string) for any memo field created using BLOBIMPORT().

■  This example imports information from a word processing
   document into a field, and then uses BLOBGET() to extract the first
   25 characters of the field:

   FUNCTION POPULATE()
      USE customer NEW VIA "DBFCDX"

      // Construct unique file name based on last
      // name and id
      DO WHILE .NOT. Eof()
         GetPix("Pix", SubStr(LastName, 1, 4) + CustID)
         Customer->dbSkip()
      ENDDO
   FUNCTION GetPix(cPixField, cPixFile)
      LOCAL nPos

      nPos := FieldPos(cPixField)

      // Import the picture file into indicated field
      IF !BLOBImport(nPos, cPixFile)
         Alert("Import of picture " + cPixFile + ";
         failed!")
      ENDIF

BLOBROOTGET() allows the retrieval of a BLOB from the root of a BLOB file in a work area. By default, this function 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.

Note: Because the root data does not reference a particular record in the database file, the dbRLock() will not protect this root storage reference. Therefore, if the database file is opened in shared mode, you should use BLOBROOTLOCK() before calling BLOBROOTGET().

■  This example uses BLOBROOTGET() to read system settings from a
   BLOB file into an array, and then demonstrates how to allow the user
   to modify the settings and restore them in the BLOB file:

   FUNCTION UPDATESETTINGS()
      LOCAL aSettings

      USE customer NEW SHARED VIA "DBFCDX"

      IF BLOBROOTLOCK()
         // Get any existing settings
         aSettings := BLOBROOTGET()

         IF Empty(aSettings)
            // This function would populate aSettings
            // with default data
            aSettings := GETDEFAULTSETTINGS()
         ENDIF

         // This function would allow the user to
         // modify the settings.
         IF ModifySettings(aSettings)
            // Finally, store the settings
            BLOBRootPut(aSettings)
         ENDIF
         BLOBROOTUNLOCK()
      ELSE
         aSettings := {}
         Alert("Could not obtain a lock on the root;
            area")
      ENDIF

      CLOSE

      RETURN aSettings

BLOBROOTLOCK() → lSuccess

Use BLOBROOTLOCK() when accessing the database file in shared mode to obtain a lock on the root area of a BLOB file for reading from or writing to the root area.

By default, this function 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.

■  This example illustrates how to properly lock and unlock the
   root area of a BLOB file for a database file opened in shared mode:

   FUNCTION GETSETTINGS()
   LOCAL aCustSettings

   // Open a customer file in shared mode
   USE customer NEW SHARED DBFCDX

   IF BLOBROOTLOCK()
      aCustSettings := BLOBROOTGET()
      BLOBROOTUNLOCK()
   ELSE
      Alert("Could not obtain root lock of Customer;
         file")
   ENDIF

   CLOSE

   RETURN aCustSettings

BLOBRootPut(<uBLOB>) → lSuccess

BLOBROOTPUT() allows the storage of one—and only one—piece of data to a BLOB file’s root area (there is no size limitation on this one piece of data). After storing the new data, BLOBROOTPUT() releases the space associated with any data previously stored in the BLOB file’s root area.

By default, this function 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.

Note: Because the root data does not reference a particular record in the database file, the dbRLock() will not protect this root storage reference. Therefore, if the database file is opened in shared mode, you should use BLOBROOTLOCK() before calling BLOBROOTPUT().

■  This example uses BLOBROOTPUT() to store system settings to a
   BLOB file after modification:

   FUNCTION UPDATESETTINGS()
      LOCAL aSettings

      USE customer NEW SHARED VIA "DBFCDX"

      IF BLOBROOTLOCK()
         // Get any existing settings
         aSettings := BLOBROOTGET()

         IF Empty(aSettings)
            // This function would populate aSettings
            // with default data
            aSettings := GETDEFAULTSETTINGS()
         ENDIF

         // This function would allow the user to
         // modify the settings.
         IF ModifySettings(aSettings)
            // Finally, store the settings
            BLOBRootPut(aSettings)
         ENDIF
         BLOBROOTUNLOCK()
      ELSE
         aSettings := {}

         Alert("Could not obtain a lock on the root;
            area")
      ENDIF

      CLOSE

      RETURN aSettings

Use BLOBROOTUNLOCK() to release a lock previously obtained using BLOBROOTLOCK().

By default, this function 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.

Note: The only functions that require the use of BLOBROOTLOCK() or BLOBROOTUNLOCK() are BLOBROOTGET() and BLOBROOTPUT().

■  This example illustrates how to properly lock and unlock the
   root area of a BLOB file for a database file opened in shared mode:

   FUNCTION GETSETTINGS()
      LOCAL aCustSettings

      // Open a customer file in shared mode
      USE customer NEW SHARED VIA DBFCDX

      IF BLOBROOTLOCK()
         aCustSettings := BLOBROOTGET()
         BLOBROOTUNLOCK()
      ELSE
         Alert("Could not obtain root lock of Customer;
            file")
      ENDIF

      CLOSE

      RETURN aCustSettings

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

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

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

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

■  This example demonstrates Bof() by attempting to move the
   record pointer before the first record:

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

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

   USE Sales NEW
   USE Customer NEW
   USE Invoices NEW

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

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

   bSave := ErrorBlock( {|x| Break(x)} )

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

   ErrorBlock(bSave)

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

■ Status line: Browse() supports a status line in the upper

right corner of the browse window indicating one of the following:

Browse() Status Line Messages

■ Browse() has the following three modes:

— Browsing: This is the default mode of Browse(). Pressing any

dbEdit() navigation key moves the highlight to a new column or row.

— Field edit: Pressing Return on any field enters field edit

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

— Append: GOing BOTTOM with Ctrl+PgDn and then pressing Down

arrow enters append mode with the indicating message «new» on the status line. A new blank record is then inserted. Pressing Up arrow terminates the append mode, saving the new record if data has been entered. If no data has been entered, the new record is not saved.

■  This is an example of browsing a file:

   USE File1 NEW
   Browse()

CALL <idProcedure> [WITH <exp list>]

idProcedure is the name of the external procedure to CALL.

WITH exp list is an optional list of up to seven expressions of any data type to pass to the external procedure.

CALL executes a separately compiled or assembled procedure. The procedure must be defined as FAR and end with a FAR return instruction. Place parameters on the stack using the C parameter passing convention. Each parameter consists of a FAR (four-byte) pointer to the actual parameter value. When necessary you may use the Word() function to pass a two-byte binary value in the WITH expression. The DX:BX and ES:BX registers also contain a copy of the first four bytes of parameter information.

The procedure must preserve the BP, SS, SI, DI, ES, and DS registers as well as clear the direction flag.

CALL is a compatibility command and therefore not recommended. It is superseded by the Extend system which provides functions for passing data to and from CA-Clipper.

■ Character strings: Pass a character argument as a FAR pointer

to a null-terminated string (a string with a 00 hex byte at the end).

■ Numeric values: Pass each numeric argument as a FAR pointer

to an eight-byte IEEE floating point value. To pass a parameter as an integer, use the Word() function. The Word() function converts the numeric value to a two-byte binary integer, and passes the integer value directly rather than through a pointer. Note that Word() will not work for values outside of the ▒32,767 range since these values cannot be accurately represented as two-byte integers.

■ Date values: Pass each date argument as a FAR pointer to a

four-byte (long) integer containing a Julian day number.

■ Logical values: Pass each logical argument as a FAR pointer

to a two-byte binary integer containing zero for false (.F.) and one for true (.T.) .

■ Compiling and linking: CALLed programs must conform to the

following rules:

— Procedures must be in INTEL 8086 relocatable object file

format with the .OBJ file extension.

— Procedures must follow the C calling and parameter passing

conventions.

— Procedures must be available to the linker at link time, along

with the library of the source compiler. You will need runtime support for any language other than assembly language. See your compiler manual for further information.

■ Screen position: When using a CALL statement to access a C or

Assembler routine, the cursor is set to the current screen position within the C or Assembler routine.

■ Microsoft C: Microsoft C versions 5.0 and above place a

leading underscore on function names when they are compiled. To call them, therefore, you must CALL _function.

■ dBASE III PLUS: To convert a dBASE III PLUS load module to a

CA-Clipper-compatible module, add the following statements to your .asm file:

PUBLIC proc

and

push ds mov ds, dx

Warning! Modifying the parameter values may produce incorrect or unexpected results and, therefore, is strongly discouraged.

■ Return code: When a CA-Clipper 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 0 or the last ErrorLevel() set in the program.

■  These examples illustrate CDoW():

   ? Date()                      // Result: 09/01/90
   ? CDoW(Date())                // Result: Friday
   ? CDoW(Date() + 7)            // Result: Friday
   ? CDoW(CToD("06/12/90"))      // Result: Tuesday

Check boxes present a choice to the user which can be either on or off. When a check box is clicked, its state is toggled (as indicated by an X in the box) between checked (on) and unchecked (off).

The CheckBox class has been designed to be easily integrated into the standard CA-Clipper GET/READ system in addition to providing the necessary functionality to be utilized on its own.

CheckBox(nRow, nColumn,

[,cCaption]) → oCheckBox

Arguments

nRow is a numeric value that indicates the screen row of the check box.

nColumn is a numeric value that indicates the screen column of the check box.

nCaption is an optional character string that describes the check box on the screen. If omitted, the default is an empty string.

Returns

Returns a CheckBox object when all of the required arguments are present; otherwise, CheckBox() returns NIL.

bitmaps (Assignable)

Contains an array of exactly two elements that indicates the bitmap files to be displayed. The first element indicates the file name of the bitmap to be displayed when the check box is selected. The second element indicates the file name of the bitmap to be displayed when the check box is not selected.

Drive and directory names are not allowed; the file name extension is required. A bitmap file can be stored as a file on disk or in a bitmap library. If stored as a file, the file must reside in the same directory as the application. If stored in a bitmap library, the library must reside in the same directory as the application and it also must have the same name as the application with a .bml extension.

CA-Clipper will search for the file name first, and if it is not found, then search in the bitmap library. If no file is found either on disk or in the library, no bitmap will be displayed.

If this instance variable is not used, and the application is running in graphic mode, the files CHECK_F.BMU and CHECK_E.BMU will be used for the selected bitmap and unselected bitmap, respectively.

This instance variable only affects applications running in graphic mode and is ignored in text mode.

buffer

Contains a logical value that indicates whether the check box is checked or unchecked. A value of true (.T.) indicates that it is checked and a value of false (.F.) indicates that it is not checked.

capCol (Assignable)

Contains a numeric value that indicates the screen column where the check box’s caption is displayed.

capRow (Assignable)

Contains a numeric value that indicates the screen row where the check box’s caption is displayed.

caption (Assignable)

Contains an optional character string that concisely describes the check box on the screen. If omitted, the default is an empty string.

When present, the & character specifies that the character immediately following it in the caption is the check box’s accelerator key. The accelerator key provides a quick and convenient mechanism for the user to move input focus from one data input control to the check box. The user performs the selection by pressing the Alt key in combination with an accelerator key. The case of an accelerator key is ignored.

cargo (Assignable)

Contains a value of any type that is ignored by the CheckBox object. CheckBox:cargo is provided as a user-definable slot allowing arbitrary information to be attached to a CheckBox object and retrieved later.

col (Assignable)

Contains a numeric value that indicates the screen column where the check box is displayed.

colorSpec (Assignable)

Contains a character string that indicates the color attributes that are used by the check box’s display() method. The string must contain four color specifiers.

Note: In graphic mode, colorSpec positions 1 and 2 have no affect and are ignored.

CheckBox Color Attributes

Note: The colors available to a DOS application are more limited than those for a Windows application. The only colors available to you here are those listed in the drop-down list box of the Workbench Properties window for that item.

fBlock (Assignable)

Contains an optional code block that, when present, is evaluated each time the CheckBox object receives or loses input focus. The code block takes no implicit arguments. Use CheckBox:hasFocus to determine if the check box is receiving or losing input focus. A value of true (.T.) indicates that it is receiving input focus; otherwise, a value of false (.F.) indicates that it is losing input focus.

This code block is included in the CheckBox class to provide a method of indicating when an input focus change event has occurred. The name «fBlock» refers to focus block.

hasFocus

Contains a logical value that indicates whether the CheckBox object has input focus. CheckBox:hasFocus contains true (.T.) if it has input focus; otherwise, it contains false (.F.).

message (Assignable)

Contains a character string that describes the check box. It is displayed on the screen’s status bar line.

row (Assignable)

Contains a numeric value that indicates the screen row where the check box is displayed.

sBlock (Assignable)

Contains an optional code block that, when present, is evaluated each time the CheckBox object’s state changes. The code block takes no implicit arguments. Use the buffer instance variable to determine if the check box is being checked or unchecked. A value of true (.T.) indicates that it is being checked; otherwise, a value of false (.F.) indicates that it is being unchecked.

This code block is included in the CheckBox class to provide a method of indicating when a state change event has occurred. The name «sBlock» refers to state block.

style (Assignable)

Contains a character string that indicates the delimiter characters that are used by the check box’s display() method. The string must contain four characters. The first is the left delimiter. Its default value is the left square bracket ([) character. The second is the checked indicator. Its default value is the square root character. The third is the unchecked indicator. Its default is the space character (» «). The fourth character is the right delimiter. Its default value is the right square bracket (]) character.

Note: The style instance variable is ignored in graphic mode.

typeOut

Contains the logical value false (.F.). CheckBox:typeOut never changes. It is not used by the CheckBox object and is only provided for compatibility with the other GUI control classes.

oCheckBox:display() → self

display() is a method of the CheckBox class that is used for showing a check box and its caption on the screen. display() uses the values of the following instance variables to correctly show the check box in its current context in addition to providing maximum flexibility in the manner a check box appears on the screen: buffer, caption, capCol, capRow, col, colorSpec, hasFocus, row, and style.

oCheckBox:hitTest(nMouseRow, nMouseCol)

→ nHitStatus

nMouseRow is a numeric value that indicates the current screen row position of the mouse cursor.

nMouseCol is a numeric value that indicates the current screen column position of the mouse cursor.

Returns a numeric value that indicates the relationship of the mouse cursor with the check box. HitTest() is a method of the CheckBox class that is used for determining if the mouse cursor is within the region of the screen that the check box or its caption occupies.

Applicable Hit Test Return Values

Button.ch contains manifest constants for the HitTest() return value.

oCheckBox:killFocus() → self

killFocus() is a method of the CheckBox class that is used for taking input focus away from a CheckBox object. Upon receiving this message, the CheckBox object redisplays itself and, if present, evaluates the code block within its fBlock variable.

This message is meaningful only when the CheckBox object has input focus.

oCheckBox:select([lNewState]) → self

lNewState is a logical value that indicates whether the check box should be checked or not. Set to true (.T.) to check the box or false to uncheck the box. If omitted, the check box state will toggle to its opposing state.

Select() is a method of the CheckBox class that is used for changing the state of a check box. Its state is typically changed when the space bar is pressed or the mouse’s left button is pressed when its cursor is within the check box’s region of the screen.

oCheckBox:setFocus() → self

setFocus() is a method of the CheckBox class that is used for giving focus to a CheckBox object. Upon receiving this message, the CheckBox object redisplays itself and if present, evaluates the code block within its fBlock variable.

This message is meaningful only when the CheckBox object does not have input focus.

■  This example creates and integrates a check box within a Get
   List and activates it by performing a READ:

   STORE SPACE (25) TO Name
   STORE .T. TO Married
   STORE SPACE (19) TO Phone

   CLS

   @    5,10 SAY "Customer Name: " GET Name
   @  7,10 SAY "Married?:     " GET Married CHECKBOX
   @  9,10 SAY "Home Phone:    " GET Phone

   READ

   ? ALLTRIM (Name) + " IS " + IIF(Married,"","NOT") + "Married."
   WAIT

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

■ Sending control codes and graphics characters to the screen or

printer

■ Ringing the bell

■ Converting Inkey() return values to characters

■ Stuffing the keyboard buffer

■ The null character: Chr(0) has a length of one (1) and is

treated like any other character. This lets you send it to any device or file, including a database file.

■  These examples illustrate Chr() with various arguments:

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

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

   ? Len("")                   // Result: 0
   ? Len(Chr(0))               // Result: 1

CLEAR ALL releases all public and private variables, closes all open databases and related files in all active work areas, and SELECTs work area 1. Related files are index, alternate, and memo files. CLEAR ALL, however, does not release local or static variables.

CLEAR ALL is a compatibility command and therefore not recommended. Its usage in CA-Clipper is superseded by the command or function that performs the specific action you need. You can close files associated with work areas with one of the various forms of the CLOSE command. You can release private and public variables using the RELEASE command although explicitly releasing variables is discouraged in most instances. For more information on the scope and lifetime of variables, refer to the «Basic Concepts» chapter in the Programming and Utilities Guide.

CLEAR GETS explicitly releases all Get objects in the current and visible GetList array, and terminates the calling READ, releasing any remaining objects in the calling READ, if executed within a SET KEY procedure or a user-defined function invoked by a VALID clause. CLEAR GETS releases Get objects by assigning an empty array to the variable GetList. GetList is the name of the variable used to hold an array of Get objects for subsequent READ commands. There are two other mechanisms that automatically release Get objects: CLEAR specified without the SCREEN clause, and READ specified without the SAVE clause.

CLEAR GETS has two basic uses. First, it can be used to terminate a READ from a SET KEY procedure or VALID user-defined function. Second, it can be used to delete Get objects from the GetList array when you have not executed a READ or you have saved the Get objects by using READ SAVE.

CLEAR MEMORY deletes both public and private memory variables from the memory variable table. It operates in contrast to RELEASE ALL, which does not actually delete public and private memory variables but assigns NIL to those whose scope is the current procedure. CLEAR MEMORY is the only way to delete all public memory variables from current memory. Local and static variables, however, are unaffected by CLEAR MEMORY.

For more information on variables, refer to the Variables section of the «Basic Concepts» chapter in the Programming and Utilities Guide.

CLEAR is a full-screen command that erases the screen, releases pending GETs, and positions the cursor at row and column zero. If the SCREEN clause is specified, Get objects are not released.

CLS is a synonym for CLEAR SCREEN.

■ SET KEY and VALID: If you are editing GETs, executing a CLEAR

within a SET KEY procedure or within a VALID user-defined function will abort the active READ when control returns. To clear the screen without CLEARing GETs, use either the CLEAR SCREEN or CLS commands.

CLEAR TYPEAHEAD is a keyboard command that clears all pending keys from the CA-Clipper keyboard buffer. This is useful in user interface procedures or user-defined functions to guarantee that keys processed from the keyboard buffer are appropriate to the current activity and not pending from a previous activity. User functions called by AChoice() and dbEdit() are especially sensitive to such keys.

Note that both the SET TYPEAHEAD and KEYBOARD commands also clear the keyboard buffer.

■  This example empties the keyboard buffer before invoking
   dbEdit(), guaranteeing that any pending keys will not be executed:

   CLEAR TYPEAHEAD
   dbEdit()

CLOSE [<idAlias> | ALL | ALTERNATE | DATABASES |
   FORMAT | INDEXES]

idAlias specifies the work area where all files are to be closed.

ALL closes alternate, database, and index files in all work areas, releasing all active filters, relations, and format definitions.

ALTERNATE closes the currently open alternate file, performing the same action as SET ALTERNATE TO with no argument.

DATABASES closes all open databases, memo and associated index files in all work areas, and releases all active filters and relations. It does not, however, have any effect on the active format.

FORMAT releases the current format, performing the same action as SET FORMAT TO with no argument.

INDEXES closes all index files open in the current work area.

CLOSE is a general purpose command that closes various types of CA-Clipper files depending on the specified option. CLOSE with no option closes the current database and associated files, the same as USE with no arguments.

In CA-Clipper, a number of other commands also close files including:

■ QUIT

■ CANCEL*

■ RETURN from the highest level procedure

■ CLEAR ALL*

■ USE with no argument

■  These examples illustrate CMonth():

   ? CMonth(Date())                     // Result: September
   ? CMonth(Date() + 45)                // Result: October
   ? CMonth(CToD("12/01/94"))           // Result: December
   ? SubStr(CMonth(Date()), 1, 3) +;
      Str(Day(Date()))                  // Result: Sep 1

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

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

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

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

USE Sales NEW

   CLS
   @ 1, 10 SAY "Customer Name: " + Trim(Customer)
   @ Row(), Col() + 1 SAY "Account status: " + Status

ColorSelect(<nColorIndex>) → NIL

ColorSelect() activates the specified color pair from the current list of color attributes (established by SetColor()). Manifest constants for nColorIndex are defined in color.ch.

Color.ch constants

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

This table describes the scope of the CA-Clipper color settings affected by SetColor():

Color settings

■  This example demonstrates use of ColorSelect() with the
   color.ch manifest constants:

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

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

COMMIT is a database command that flushes CA-Clipper buffers and performs a solid-disk write for all work areas with open database and index files. The solid-disk write capability is available under DOS version 3.3 and above. Under DOS 3.2 or less, COMMIT flushes CA-Clipper buffers to DOS.

In a network environment, issuing a GO TO RecNo() or a SKIP0 will flush CA-Clipper’s database and index buffers, but only a COMMIT will flush the buffers and perform a solid-disk write. Thus to insure updates are visible to other processes, you must issue a COMMIT after all database update commands (e.g., APPEND, REPLACE). To insure data integrity, COMMIT should be issued before an UNLOCK operation. Refer to the «Network Programming» chapter in the Programming and Utilities Guide for more information on update visibility.

■ COMMIT uses DOS interrupt 21h function 68h to perform the

solid-disk write. It is up to the network operating system to properly implement this request. Check with the network vendor to see if this is supported.

■  In this example, COMMIT forces a write to disk after a series
   of memory variables are assigned to field variables:

   USE Sales EXCLUSIVE NEW
   MEMVAR->Name := Sales->Name
   MEMVAR->Amount := Sales->Amount
   //
   @ 10, 10 GET MEMVAR->Name
   @ 11, 10 GET MEMVAR->Amount
   READ
   //
   IF Updated()
      APPEND BLANK
      REPLACE Sales->Name WITH MEMVAR->Name
      REPLACE Sales->Amount WITH MEMVAR->Amount
      COMMIT
   ENDIF

CONTINUE is a database command that searches from the current record position for the next record meeting the most recent LOCATE condition executed in the current work area. It terminates when a match is found or end of file is encountered. If CONTINUE is successful, the matching record becomes the current record and Found() returns true (.T.); if unsuccessful, Found() returns false (.F.).

Each work area may have an active LOCATE condition. In CA-Clipper, a LOCATE condition remains pending until a new LOCATE condition is specified. No other commands release the condition.

■ Scope and WHILE condition: Note that the scope and WHILE

condition of the initial LOCATE are ignored; only the FOR condition is used with CONTINUE. If you are using a LOCATE with a WHILE condition and want to continue the search for a matching record, use SKIP and then repeat the original LOCATE statement adding REST as the scope.

■  This example scans records in Sales.dbf for a particular
   salesman and displays a running total sales amounts:

   LOCAL nRunTotal := 0
   USE Sales NEW
   LOCATE FOR Sales->Salesman = "1002"
   DO WHILE Found()
      ? Sales->Salesname, nRunTotal += Sales->Amount
      CONTINUE
   ENDDO

■  This example demonstrates how to continue if the pending
   LOCATE scope contains a WHILE condition:

   LOCAL nRunTotal := 0
   USE Sales INDEX Salesman NEW
   SEEK "1002"
   LOCATE REST WHILE Sales->Salesman = "1002";
         FOR Sales->Amount > 5000
   DO WHILE Found()
      ? Sales->Salesname, nRunTotal += Sales->Amount
      SKIP
      LOCATE REST WHILE Sales->Salesman = "1002";
         FOR Sales->Amount > 5000
   ENDDO

COPY FILE <xcSourceFile> TO <xcTargetFile>|<xcDevice>

xcSourceFile is the name of the source file to copy including the extension.

xcTargetFile is the name of the target file including the extension.

Both arguments can be specified as literal file names or as character expressions enclosed in parentheses. COPY FILE supplies no default extensions.

xcDevice is the name of the device where all subsequent output will be sent. You can specify a device name as a literal character string or a character expression enclosed in parentheses. Additionally, a device can be either local or network. If you COPY TO a non-existing device, you create a file with the name of the device. When specifying device names, do not use a trailing colon.

■  This example copies a file to a new file and then tests for
   the existence of the new file:

   COPY FILE Test.prg TO Real.prg
   ? FILE("Real.prg")                  // Result: .T.

COPY STRUCTURE [FIELDS <idField list>]
   TO <xcDatabase>

FIELDS idField list defines the set of fields to copy to the new database structure in the order specified. The default is all fields.

TO xcDatabase is the name of the target database file and can be specified either as a literal database file name or as a character expression enclosed in parentheses. The default extension is .dbf unless another is specified.

COPY STRUCTURE is a database command that creates an empty database file with field definitions from the current database file. If xcDatabase exists, it is overwritten.

COPY STRUCTURE creates empty structures that can be used to archive records from the current database file or to create a temporary database file for data entry.

■  In this example, COPY STRUCTURE creates a temporary file.
   After the user enters data into the temporary file, the master
   database file is updated with the new information:

   USE Sales NEW
   COPY STRUCTURE TO Temp
   USE Temp NEW
   lMore := .T.
   DO WHILE lMore
      APPEND BLANK
      @ 10, 10 GET Temp->Salesman
      @ 11, 11 GET Temp->Amount
      READ
      IF Updated()
         SELECT Sales
         APPEND BLANK
         REPLACE Sales->Salesman WITH Temp->Salesman
         REPLACE Sales->Amount WITH Temp->Amount
         SELECT Temp
         ZAP
      ELSE
         lMore := .F.
      ENDIF
   ENDDO
   CLOSE DATABASES

COPY STRUCTURE EXTENDED
   TO <xcExtendedDatabase>

COPY STRUCTURE EXTENDED creates a database file whose contents is the structure of the current database file with a record for the definition of each field. The structure extended database file has the following structure:

Structure of an Extended File

Used in application programs, COPY STRUCTURE EXTENDED permits you to create or modify the structure of a database file programmatically. To create a new database file from the structure extended file, use CREATE FROM. If you need an empty structure extended file, use CREATE.

■ Character field lengths greater than 255: In CA-Clipper, the

maximum character field length is 64K. For compatibility reasons, field lengths greater than 255 are represented as a combination of the Field_dec and Field_len fields. After COPYing STRUCTURE EXTENDED, you can use the following formula to determine the length of any character field:

nFieldLen := IF(Field_type = «C» .AND. ;

Field_dec != 0, Field_dec * 256 + ; Field_len, Field_len)

■  This example creates Struc.dbf from Sales.dbf as a structure
   extended file and then lists the contents of Struc.dbf to illustrate
   the typical layout of field definitions:

   USE Sales NEW
   COPY STRUCTURE EXTENDED TO Struc
   USE Struc NEW
   LIST Field_name, Field_type, Field_len, Field_dec

   Result:

   1 BRANCH        C      3      0
   2 SALESMAN      C      4      0
   3 CUSTOMER      C      4      0
   4 PRODUCT       C     25      0
   5 AMOUNT        N      8      2
   6 NOTES         C      0    125
   // Field length is 32,000 characters

COPY [FIELDS <idField list>] TO <xcFile>
   [<scope>] [WHILE <lCondition>] [FOR <lCondition>]
   [SDF | DELIMITED [WITH BLANK | <xcDelimiter>] |
   [VIA <xcDriver>]]

FIELDS idField list specifies the list of fields to copy to the target file. The default is all fields.

TO xcFile specifies the name of the target file. The file name can be specified either as a literal file name or as a character expression enclosed in parentheses. If SDF or DELIMITED is specified, .txt is the default extension. Otherwise, .dbf is the default extension.

scope defines the portion of the current database file to COPY. 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 copy within the given scope.

SDF specifies the output file type as a System Data Format ASCII text file. Records and fields are fixed length.

DELIMITED specifies the output file type as a delimited ASCII text file where character fields are enclosed in double quotation marks (the default delimiter). Records and fields are variable length.

DELIMITED WITH BLANK identifies an ASCII text file in which fields are separated by one space and character fields have no delimiters.

DELIMITED WITH xcDelimiter identifies a delimited ASCII text file where character fields are enclosed using the specified delimiter. xcDelimiter can be specified either as a literal character or as a character expression enclosed in parentheses.

See the tables below for more information regarding the format specifications for ASCII text files created using these arguments.

VIA xcDriver specifies the replaceable database driver (RDD) to use to create the resulting copy. 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 omitted, COPY TO uses the driver in the current work area. If you specify the VIA clause, you must REQUEST the appropriate RDDs to be linked into the application.

Note: If the DELIMITED WITH clause is specified on a COPY or APPEND command, it must be the last clause specified.

COPY TO is a database command that copies all or part of the current database file to a new file. Records contained in the active database file are copied unless limited by a scope, a FOR|WHILE clause, or a filter.

If DELETED is OFF, deleted records in the source file are copied to xcFile where they retain their deleted status. If DELETED is ON, however, no deleted records are copied. Similarly, if a FILTER has been SET, invisible records are not copied.

Records are copied in controlling index order if there is an index open in the current work area and SET ORDER is not zero. Otherwise, records are copied in natural order.

In a network environment, CA-Clipper opens the target database file EXCLUSIVEly before the COPY TO operation begins. Refer to the «Network Programming» chapter in the Programming and Utilities Guide for more information.

This table shows the format specifications for SDF text files:

SDF Text File Format Specifications

This table shows the format specifications for DELIMITED and DELIMITED WITH xcDelimiter ASCII text files:

DELIMITED Text File Format Specifications

This table shows the format specifications for DELIMITED WITH BLANK ASCII text files:

DELIMITED WITH BLANK Text File Format Specifications

■  This example demonstrates copying to another database file:

   USE Sales NEW
   COPY TO Temp

■  This example demonstrates the layout of a DELIMITED file:

   COPY NEXT 1 TO Temp DELIMITED
   TYPE Temp.txt

   Result:

   "Character",12.00,19890801,T

■  This example demonstrates the layout of an SDF file with four
   fields, one for each data type:

   USE Testdata NEW
   COPY NEXT 1 TO Temp SDF
   TYPE Temp.txt

   Result:

   Character     12.0019890801T

■  This example demonstrates the layout of a DELIMITED file WITH
   a different delimiter:

   COPY NEXT 1 TO Temp DELIMITED WITH '
   TYPE Temp.txt

   Result:

   'Character',12.00,19890801,T

COUNT TO <idVar>
   [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

TO idVar identifies the variable that holds the COUNT result. A variable that either does not exist or is invisible is created as a private variable whose scope is the current procedure.

scope is the portion of the current database file to COUNT. 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 COUNT within the given scope.

■  This example demonstrates a COUNT of Branches in Sales.dbf:

   USE Sales NEW
   COUNT TO nBranchCnt FOR Branch = 100
   ? nBranchCnt                           // Result: 4

■  This example tallies the number of records in Sales.dbf whose
   Branch has the value of 100 and assigns the result to the Count field
   in Branch.dbf for branch 100:

   USE Branch INDEX Branch NEW
   SEEK 100
   USE Sales INDEX SalesBranch NEW
   SEEK 100
   COUNT TO Branch->Count WHILE Branch = 100

CREATE <xcExtendedDatabase>

CREATE produces an empty structure extended database file with the following structure:

Structure of an Extended File

Like COPY STRUCTURE EXTENDED, CREATE can be used in conjunction with CREATE FROM to form a new database file. Unlike COPY STRUCTURE EXTENDED, CREATE produces an empty database file and does not require the presence of another database file to create it.

xcExtendedDatabase is automatically opened in the current work area after it is created.

■  This example creates a new structure extended file, places the
   definition of one field into it, and then CREATEs a new database file
   FROM the extended structure:

   CREATE TempStru
   APPEND BLANK
   REPLACE Field_name WITH "Name",;
      Field_type WITH "C",;
      Field_len WITH 25,;
      Field_dec WITH 0
   CLOSE
   CREATE NewFile FROM TempStru

CREATE <xcDatabase> FROM <xcExtendedDatabase> [NEW]
   [ALIAS <xcAlias>] [VIA <cDriver>]

xcDatabase is the name of the new database file to create from the structure extended file.

xcExtendedDatabase is the name of a structure extended file to use as the structure definition for the new database file.

Both of these arguments can be specified either as literal database file names or as character expressions enclosed in parentheses. If an extension is not specified, the default is .dbf.

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.

ALIAS xcAlias is the name to associate with the work area when xcDatabase is opened. You may specify the alias name as a literal name or as a character expression enclosed in parentheses. A valid xcAlias may be any legal identifier (i.e., it must begin with an alphabetic character and may contain numeric or alphabetic characters and the underscore). Within a single application, CA-Clipper will not accept duplicate aliases. If this clause is not specified, the alias defaults to the database file name.

VIA cDriver specifies the replaceable database driver (RDD) to use to process the current work area. cDriver is the name of the RDD specified as a character expression. If you specify cDriver as a literal value, you must enclose it in quotes.

CREATE FROM produces a new database file with the field definitions taken from the contents of a structure extended file. To qualify as a structure extended file, a database file must contain the following four fields:

Structure of an Extended File

xcDatabase is automatically opened in the current work area after it is created.

■ Data dictionaries: For data dictionary applications, you can

have any number of other fields within the structure extended file to describe the extended field attributes. You may, for example, want to have fields to describe such field attributes as a description, key flag, label, color, picture, and a validation expression for the VALID clause. When you CREATE FROM, CA-Clipper creates the new database file from the required fields only, ignoring all other fields in the extended structure. Moreover, CA-Clipper is not sensitive to the order of the required fields.

■ Character field lengths greater than 255: There is one method

for creating a character field with a length greater than 255 digits:

— Specify the field length using both the Field_len and

Field_dec fields according to the following formulation:

FIELD->Field_len := nFieldLength % 256 FIELD->Field_dec := INT(nFieldLength / 256)

■  This example is a procedure that simulates an interactive
   CREATE utility:

   CreateDatabase("NewFile")
   RETURN

   FUNCTION CreateDatabase( cNewDbf )
      CREATE TmpExt          // Create empty structure extended
      USE TmpExt
      lMore := .T.
      DO WHILE lMore         // Input new field definitions
         APPEND BLANK
         CLEAR
         @ 5, 0 SAY "Name.....: " GET Field_name
         @ 6, 0 SAY "Type.....: " GET Field_type
         @ 7, 0 SAY "Length...: " GET Field_len
         @ 8, 0 SAY "Decimals.: " GET Field_dec
         READ
         lMore := (!Empty(Field_name))
      ENDDO

      // Remove all blank records
      DELETE ALL FOR Empty(Field_name)
      PACK
      CLOSE

      // Create new database file
      CREATE (cNewDbf) FROM TmpExt
      ERASE TmpExt.dbf
      RETURN NIL

■  This example creates a new definition in a structure extended
   file for a character field with a length of 4000 characters:

   APPEND BLANK
   REPLACE Field_name WITH "Notes",;
      Field_type WITH "C",;
      Field_len  WITH 4000 % 256,;
      Field_dec  WITH INT(4000 / 256)

CToD() is a character conversion function that converts a character string to a date. To initialize an empty date for date entry, specify cDate as a null string («»), Space(8), or » / / «.

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

■ Initializing a variable to a date value

■ Specifying a literal date string as an argument of a RANGE

clause of @...GET

■ Specifying a literal date string in order to perform date

arithmetic

■ Comparing the result of a date expression to a literal date

string

■ REPLACEing a date field with a literal date string

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

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

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

■  This example uses CToD() to create a date value within a FOR
   condition:

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

CurDir([<cDrivespec>]) → cDirectory

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

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

■  These examples illustrate various CurDir() results:

   ? CurDir("E:")     // Result: null string--root directory
   ? CurDir("C")      // Result: CLIP53SOURCE
   ? CurDir("C:")     // Result: CLIP53SOURCE
   ? CurDir()         // Result: null string--root directory
   ? CurDir("A")      // Result: null string--drive not ready

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

   IF CurDir("C:") != "CLIP53SOURCE"
      RUN CD CLIP53SOURCE
   ENDIF

dbAppend([<lReleaseRecLocks>]) → NIL

dbAppend() is a database function that lets you add records to the current database. The enhancement to this function lets you maintain multiple record locks during an append.

dbAppend() without a parameter as in earlier versions of CA-Clipper, clears all pending record locks prior to an append. This is the same as dbAppend(.T.).

■  This example appends a blank record to the database, Sales,
   without releasing the record locks in the current Lock List, and then
   checks for a network error:

   USE Sales NEW
   SET INDEX TO Sales
   dbAppend(.F.)
   IF NetErr()
      ? "A network error has occurred!"
   ENDIF

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.

■ Logical records: dbClearFilter() affects the logical

visibility of records in the current work area. For more information, refer to dbSetFilter() and the SET FILTER command.

■  The following example sets a filter, lists data as filtered,
   and then clears the filter:

   USE Employee NEW
   dbSetFilter( {|| Age < 40}, "Age < 40" )
   LIST Employee->Name
   dbClearFilter()

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.

■  The following example clears index files if any are set:

   cFirst := "Winston"
   dbUseArea( .T., "DBFNTX", "Sales", "Sales", .T. )
   dbSetIndex( "FIRSTNAM" )
   dbSetIndex( "LASTNAME" )
   //
   IF IndexOrd() > 0               // is there an index?
      dbClearIndex()               // clear index files
   ELSE
      COPY TO FILE TEMP SDF      // copy to SDF in natural
   ENDIF                           // order

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.

■  The following example sets a relation, lists data, and then
   clears the relation:

   USE Employee NEW
   USE Department NEW INDEX Dept
   //
   SELECT Employee
   dbSetRelation("Department", ;
      {|| Employee->Dept}, "Employee->Dept")
   LIST Employee->Name, Department->Name
   dbClearRelation()

■  The following example closes all work areas:

   cLast := "Winston"
   dbUseArea( .T., "DBFNTX", "Sales", "Sales", .T. )
   dbSetIndex( "SALEFNAM" )
   dbSetIndex( "SALELNAM" )
   //
   dbUseArea( .T., "DBFNTX", "Colls", "Colls", .T. )
   dbSetIndex( "COLLFNAM" )
   dbSetIndex( "COLLLNAM" )
   //
   dbSelectArea( "Sales" )      // select "Sales" work area
   //

   IF ( Sales->(dbSeek(cLast)) )
      IF Sales->( Deleted() )
         IF RLock()
            Sales->( dbRecall() )
            ? "Record deleted: ", Sales( Deleted() )
         ENDIF
      ENDIF
   ELSE
      ? "Not found"
   ENDIF
   dbCloseAll()                  // close all work areas

■  The following example closes a work area via an alias
   reference:

   cLast := "Winston"
   //
   dbUseArea( .T., "DBFNTX", "Sales", "Sales", .T. )
   dbSetIndex( "SALEFNAM" )
   dbSetIndex( "SALELNAM" )
   //
   dbUseArea( .T., "DBFNTX", "Colls", "Colls", .T. )
   dbSetIndex( "COLLFNAM" )
   dbSetIndex( "COLLLNAM" )
   //
   dbSelectArea( "Sales" )      // select "Sales" work area
   //
   IF ( Sales->(dbSeek(cLast)) )

      IF Sales->( Deleted() ) .AND. Sales->( RLock() )
         Sales->( dbRecall() )
         ? "Record deleted: ", Sales( Deleted() )
      ENDIF
   ELSE
      ? "Not found"
      Colls->( dbCloseArea() )
   ENDIF

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.

■ Network environment: dbCommit() makes database updates visible

to other processes. To insure data integrity, issue dbCommit() before an UNLOCK operation. For more information, refer to the «Network Programming» chapter in the Programming and Utilities Guide.

■ dbCommit() uses DOS interrupt 21h function 68h to perform the

solid-disk write. It is up to the network operating system to properly implement this request. Check with the network vendor to see if this is supported.