Daily Archives: February 15, 2014

CLEAR MEMORY

Posted on by vivaclipper

CLEAR MEMORY

Release all public and private variables

Syntax

      CLEAR MEMORY

Description

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.

Seealso

RELEASE

? | ??

Posted on by vivaclipper

?|??

Display one or more values to the console

Syntax

       ? | ?? [<exp list>]

Arguments

<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.

Description

? 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.

Examples

       .  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

Seealso

@…SAY, PAD(), QOUT(), SET ALTERNATE, SET CONSOLE, SET PRINTER

CLEAR GETS

Posted on by vivaclipper

CLEAR GETS

Release Get objects from the current GetList array

Syntax

       CLEAR GETS

Description

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.

Seealso

@…CLEAR, @…GET, CLOSE, READ, RELEASE, SET TYPEAHEAD

CLEAR ALL

Posted on by vivaclipper

CLEAR ALL*

Close files and release public and private variables

Syntax

      CLEAR ALL

Description

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 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.

Seealso

CLEAR GETS, CLEAR MEMORY, CLOSE, RELEASE

CANCEL

Posted on by vivaclipper

CANCEL*

Terminate program processing

Syntax

      CANCEL* | QUIT

Description

CANCEL and QUIT both terminate the current program, closing all open files, and returning control to the operating system. You can use either command from anywhere in a Clipper program system. A RETURN executed at the highest level procedure performs the same action. Note that CANCEL is a compatibility command. QUIT should be used in its place.

Notes

. Return code: When a 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.

Seealso

ERRORLEVEL(), QUIT, RETURN

AVERAGE

Posted on by vivaclipper

AVERAGE

Average numeric expressions in the current work area

Syntax

      AVERAGE <nExp list> TO <idVar list>
             [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

Arguments

<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.

Description

AVERAGE calculates the average of one or more numeric expressions to variables for a range of records in the current database file. Zero values are counted in the AVERAGE unless explicitly ruled out with a FOR condition.

Examples

      .  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

Seealso

DBEVAL(), SUM, TOTAL

APPEND FROM

Posted on by vivaclipper

APPEND FROM

Import records from a database (.dbf) file or ASCII text file

Syntax

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

Arguments

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 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.

Description

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, Clipper automatically arbitrates contention for the new record.

When you invoke APPEND FROM, 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
 ------------------------------------------------------------------------
 File Element Format
 ------------------------------------------------------------------------
 Character fields Padded with trailing blanks
 Date fields yyyymmdd
 Logical fields T or F
 Memo fields Ignored
 Numeric fields Padded with leading blanks or zeros
 Field separator None
 Record separator Carriage return/linefeed
 End of file marker 1A hex or CHR(26)
 ------------------------------------------------------------------------

 This table shows the format specifications for DELIMITED and DELIMITED
 WITH <xcDelimiter> ASCII text files:
 DELIMITED Text File Format Specifications
 ------------------------------------------------------------------------
 File Element Format
 ------------------------------------------------------------------------
 Character fields May be delimited, with trailing blanks truncated
 Date fields yyyymmdd
 Logical fields T or F
 Memo fields Ignored
 Numeric fields Leading zeros may be truncated
 Field separator Comma
 Record separator Carriage return/linefeed
 End of file marker 1A hex or CHR(26)
 ------------------------------------------------------------------------

 This table shows the format specifications for DELIMITED WITH BLANK
 ASCII text files:
 DELIMITED WITH BLANK Text File Format Specifications
 ------------------------------------------------------------------------
 File Element Format
 ------------------------------------------------------------------------
 Character fields Not delimited, trailing blanks may be truncated
 Date fields yyyymmdd
 Logical fields T or F
 Memo fields Ignored
 Numeric fields Leading zeros may be truncated
 Field separator Single blank space
 Record separator Carriage return/linefeed
 End of file marker 1A hex or CHR(26)
 ------------------------------------------------------------------------

Notes

. 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, 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.

. CAUTION:

The  FROM <xcFile> (source file) shouldn’t be open and should be accessible. Otherwise 0 (zero) record will be appended.

Sample :

PROCEDURE MAIN()
   USE SOURCE
   COPY STRU TO TARGET
   SELE B 
   USE TARGET
   APPEND FROM SOURCE
   ? LASTREC() // IF "SELE B" active, 0 else > 0
RETURN // MAIN()

Examples

      .  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

Seealso

COPY TO

APPEND BLANK

Posted on by vivaclipper

APPEND BLANK

Add a new record to the current database file

Syntax

      APPEND BLANK

Description

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.

Examples

      .  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

Seealso

APPEND FROM, FLOCK(), NETERR(), RLOCK()

ACCEPT

Posted on by vivaclipper

ACCEPT*

Place keyboard input into a memory variable

Syntax

      ACCEPT [<expPrompt>] TO <idVar>

Arguments

<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.

Description

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>.

Examples

      .  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

Seealso

@…GET, @…SAY, INKEY(), INPUT*, KEYBOARD, WAIT*

@…TO

Posted on by vivaclipper

@…TO

Draw a single- or double-line box

Syntax

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

Arguments

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

Description

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

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

@…TO is 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.

Examples

       .  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"

Seealso

@…BOX, @…CLEAR, DISPBOX()