C5_CREATE FROM

 CREATE FROM
 Create a new .dbf file from a structure extended file
------------------------------------------------------------------------------
 Syntax

     CREATE <xcDatabase> FROM <xcExtendedDatabase> [NEW]
        [ALIAS <xcAlias>] [VIA <cDriver>]

 Arguments

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

 Description

     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
     ------------------------------------------------------------------------
     Field   Name           Type        Length    Decimals
     ------------------------------------------------------------------------
     1       Field_name     Character   10
     2       Field_type     Character   1
     3       Field_len      Numeric     3         0
     4       Field_dec      Numeric     4         0
     ------------------------------------------------------------------------

     <xcDatabase> is automatically opened in the current work area after it
     is created.

 Notes

     .  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, Clipper creates the new
        database file from the required fields only, ignoring all other
        fields in the extended structure.  Moreover, 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)

 Examples

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

 Files   Library is CLIPPER.LIB.

See Also: COPY STRUCTURE COPY STRU EXTE CREATE



C5_CREATE

 CREATE
 Create an empty structure extended (.dbf) file
------------------------------------------------------------------------------
 Syntax

     CREATE <xcExtendedDatabase>

 Arguments

     <xcExtendedDatabase> is the name of the empty structure extended
     database file.  This argument can be specified either as a literal
     database file name or as a character expression enclosed in parentheses.
     If no extension is specified, .dbf is the default extension.

 Description

     CREATE produces an empty structure extended database file with the
     following structure:

     Structure of an Extended File
     ------------------------------------------------------------------------
     Field   Name           Type        Length    Decimals
     ------------------------------------------------------------------------
     1       Field_name     Character   10
     2       Field_type     Character   1
     3       Field_len      Numeric     3         0
     4       Field_dec      Numeric     4         0
     ------------------------------------------------------------------------

     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.

 Examples

     .  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

 Files   Library is CLIPPER.LIB.

See Also: COPY STRU EXTE CREATE FROM



C5_COUNT

 COUNT
 Tally records to a variable
------------------------------------------------------------------------------
 Syntax

     COUNT TO <idVar>
        [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

 Arguments

     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.

 Description

     COUNT tallies the number of records from the current work area that
     match the specified record scope and conditions.  The result is then
     placed in the specified variable.  <idVar> can be a variable of any
     storage class including a field.

 Examples

     .  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

 Files   Library is CLIPPER.LIB.

See Also: AVERAGE DBEVAL() SUM TOTAL

 

C5_COPY TO

 COPY TO
 Export records to a new database (.dbf) file or ASCII text file
------------------------------------------------------------------------------
 Syntax

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

 Arguments

     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.

 Description

     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, 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
     ------------------------------------------------------------------------
     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 for 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    Delimited, with trailing blanks truncated
     Date fields         yyyymmdd
     Logical fields      T or F
     Memo fields         Ignored
     Numeric fields      Leading zeros 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 truncated
     Date fields         yyyymmdd
     Logical fields      T or F
     Memo fields         Ignored
     Numeric fields      Leading zeros truncated
     Field separator     Single blank space
     Record separator    Carriage return/linefeed
     End of file marker  1A hex or CHR(26)
     ------------------------------------------------------------------------

 Examples

     .  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

 Files   Library is CLIPPER.LIB.

See Also: APPEND FROM COPY FILE COPY STRUCTURE SET DELETED



C5_COPY STRUCTURE EXTENDED

 COPY STRUCTURE EXTENDED
 Copy field definitions to a .dbf file
------------------------------------------------------------------------------
 Syntax

     COPY STRUCTURE EXTENDED
        TO <xcExtendedDatabase>

 Arguments

     TO <xcExtendedDatabase> is the name of the target structure extended
     database file.  This argument can be specified either as a literal
     database file name or as a character expression enclosed in parentheses.

 Description

     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
     ------------------------------------------------------------------------
     Field   Name           Type         Length    Decimals
     ------------------------------------------------------------------------
     1       Field_name     Character    10
     2       Field_type     Character    1
     3       Field_len      Numeric      3         0
     4       Field_dec      Numeric      4         0
     ------------------------------------------------------------------------

     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.

 Notes

     .  Character field lengths greater than 255: In 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)

 Examples

     .  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

 Files   Library is CLIPPER.LIB.


See Also: COPY STRUCTURE CREATE CREATE FROM FIELDNAME() TYPE()

 

C5_COPY STRUCTURE

 COPY STRUCTURE
 Copy the current .dbf structure to a new database (.dbf) file
------------------------------------------------------------------------------
 Syntax

     COPY STRUCTURE [FIELDS <idField list>]
        TO <xcDatabase>

 Arguments

     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.

 Description

     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.

 Examples

     .  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

 Files   Library is CLIPPER.LIB.

See Also: COPY STRU EXTE CREATE



C5_COPY FILE

 COPY FILE
 Copy a file to a new file or to a device
------------------------------------------------------------------------------
 Syntax

     COPY FILE <xcSourceFile> TO <xcTargetFile>|<xcDevice>

 Arguments

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

 Description

     COPY FILE is a file command that copies files to and from the Clipper
     default drive and directory unless you specify a drive and/or path.  If
     the <xcTargetFile> exists, it is overwritten without warning or error.

 Examples

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

 Files   Library is EXTEND.LIB.

See Also: COPY TO RENAME SET DEFAULT



C5_CONTINUE

 CONTINUE
 Resume a pending LOCATE
------------------------------------------------------------------------------
 Syntax

     CONTINUE

 Description

     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 Clipper, a
     LOCATE condition remains pending until a new LOCATE condition is
     specified.  No other commands release the condition.

 Notes

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

 Examples

     .  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

 Files   Library is CLIPPER.LIB.

See Also: EOF() FOUND() LOCATE SEEK

 

C5_COMMIT

 COMMIT
 Perform a solid-disk write for all active work areas
------------------------------------------------------------------------------
 Syntax

     COMMIT

 Description

     COMMIT is a database command that flushes 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 Clipper
     buffers to DOS.

     In a network environment, issuing a GO TO RECNO() or a SKIP0 will flush
     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.

 Notes

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

 Examples

     .  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

 Files   Library is CLIPPER.LIB.

See Also: DBCOMMIT() DBCOMMITALL() GO SKIP

 

C5_CLOSE

 CLOSE
 Close a specific set of files
------------------------------------------------------------------------------
 Syntax

     CLOSE [<idAlias> | ALL | ALTERNATE | DATABASES |
        FORMAT | INDEXES]

 Arguments

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

 Description

     CLOSE is a general purpose command that closes various types of
     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 Clipper, a number of other commands also close files including:

     .  QUIT

     .  CANCEL*

     .  RETURN from the highest level procedure

     .  CLEAR ALL*

     .  USE with no argument

 Files   Library is CLIPPER.LIB.

See Also: QUIT RETURN SET ALTERNATE SET INDEX USE