CREATE FROM

Create new database file from a structure extended file

Syntax

      CREATE <xcFileName> FROM <xcFileFrom> [VIA <xcRDDName>];
              [NEW] [ALIAS <xcAlias>]

Arguments

<xcFileName&gt : is the target file name to create and then open. (.dbf) is the default extension if none is given. It can be specified as literal file name or as a character expression enclosed in parentheses.

<FROM xcFileFrom> : is a structure extended file name from which the target file <xcFileName> is going to be built. It can be specified as literal file name or as a character expression enclosed in parentheses.

<VIA xcRDDName> : is RDD name to create target with. If omitted, the default RDD is used. It can be specified as literal name or as a character expression enclosed in parentheses.

<NEW> : open the target file name <xcFileName> in the next available unused work-area and making it the current work-area. If omitted open the target file in current work-area.

<ALIAS xcAlias>  :  is an optional alias to USE the target file with. If not specified, alias is based on the root name of <xcFileName>.

Description

CREATE FROM open a structure extended file <xcFileFrom> where each record contain at least the following fields (in no particular order): FIELD_NAME, FIELD_TYPE, FIELD_LEN and FIELD_DEC. Any other field is ignored. From this information the file <xcFileName> is then created and opened in the current or new work-area (according to the NEW clause), if this is a new work-area it becomes the current.

For prehistoric compatibility reasons, structure extended file Character fields which are longer than 255 characters should be treated in a special way by writing part of the length in the FIELD_DEC according to the following formula:

      FIELD->FIELD_DEC := int( nLength / 256 )
      FIELD->FIELD_LEN := ( nLength % 256 )

CREATE FROM command is preprocessed into __dbCopyStruct() function during compile time and uses this mode.

Examples

      See example in the CREATE command

Compliance

Clipper

Platforms

All

Seealso

COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE, DBCREATE(), DBSTRUCT(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate()

CREATE

 

Create empty structure extended file

Syntax

      CREATE <xcFileName> [VIA <xcRDDName>] [ALIAS <xcAlias>]

Arguments

<xcFileName> : is the target file name to create and then open. (.dbf) is the default extension if none is given. It can be specified as literal file name or as a character expression enclosed in parentheses.

<VIA xcRDDName> :is RDD name to create target with. If omitted, the default RDD is used. It can be specified as literal name or as a character expression enclosed in parentheses.

<ALIAS xcAlias> : is an optional alias to USE the target file with. If not specified, alias is based on the root name of <xcFileName>.

Description

CREATE a new empty structure extended file with the name <cFileName> and then open it in the current work-area. The new file has the following structure:

       Field name   Type   Length   Decimals
       ------------ ----   ------   --------
       FIELD_NAME   C      10       0
       FIELD_TYPE   C      1        0
       FIELD_LEN    N      3        0
       FIELD_DEC    N      3        0

CREATE command is preprocessed into __dbCopyStruct() function during compile time and use this mode.

Examples

      // CREATE a new structure extended file, append some records and
      // then CREATE FROM this file a new database file

      CREATE template
      APPEND BLANK
      FIELD->FIELD_NAME := "CHANNEL"
      FIELD->FIELD_TYPE := "N"
      FIELD->FIELD_LEN  := 2
      FIELD->FIELD_DEC  := 0
      APPEND BLANK
      FIELD->FIELD_NAME := "PROGRAM"
      FIELD->FIELD_TYPE := "C"
      FIELD->FIELD_LEN  := 20
      FIELD->FIELD_DEC  := 0
      APPEND BLANK
      FIELD->FIELD_NAME := "REVIEW"
      FIELD->FIELD_TYPE := "C"      // this field is 1000 char long
      FIELD->FIELD_LEN  := 232      // 1000 % 256 = 232
      FIELD->FIELD_DEC  := 3        // 1000 / 256 = 3
      CLOSE
      CREATE TV_Guide FROM template

Compliance

Clipper

Platforms

All

Seealso

COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE FROM, DBCREATE(), DBSTRUCT(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate()

COPY STRUCTURE EXTENDED

Copy current database structure into a definition file

Syntax

      COPY STRUCTURE EXTENDED TO <xcFileName>

Arguments

<xcFileName> The name of the target definition file to create. (.dbf) is the default extension if none is given. It can be specified as a literal file name or as a character expression enclosed in parentheses.

Description

COPY STRUCTURE EXTENDED create a new database named <cFileName> with a pre-defined structure (also called “structure extended file” ) :

       Field name   Type   Length   Decimals
       -----------  ----   ------   ---------  
       FIELD_NAME   C      10       0
       FIELD_TYPE   C      1        0
       FIELD_LEN    N      3        0
       FIELD_DEC    N      3        0

Each record in the new file contains information about one field in the original file. CREATE FROM could be used to create a database from the structure extended file.

For prehistoric compatibility reasons, Character fields which are longer than 255 characters are treated in a special way by writing part of the length in the FIELD_DEC according to the following formula (this is done internally) :

      FIELD->FIELD_DEC := int( nLength / 256 ) 
      FIELD->FIELD_LEN := ( nLength % 256 )

Later if you want to calculate the length of a field you can use the following formula:

      nLength := iif( FIELD->FIELD_TYPE == "C", ;
                      FIELD->FIELD_DEC * 256 + FIELD->FIELD_LEN, ;
                      FIELD->FIELD_LEN )

COPY STRUCTURE EXTENDED command is preprocessed into __dbCopyXStruct() function during compile time.

Examples

      // Open a database, then copy its structure to a new file,
      // Open the new file and list all its records
      USE Test
      COPY STRUCTURE EXTENDED TO TestStru
      USE TestStru
      LIST

Compliance

Clipper

Platforms

All

Seealso

COPY STRUCTURE, CREATE, CREATE FROM, DBCREATE(), DBSTRUCT(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate()

COPY STRUCTURE

 

Create a new database based on current database structure

Syntax

      COPY STRUCTURE TO <xcFileName> [FIELDS <field,...>]

Arguments

TO <xcFileName> is the name of the new database file to create. (.dbf) is the default extension if none is given. It can be specified as a literal file name or as a character expression enclosed in parentheses.

FIELDS <field, …> is an optional list of field names to copy from the currently open database in the specified order, the default is all fields. Names could be specified as uppercase or lowercase.

Description

COPY STRUCTURE create a new empty database file with a structure that is based on the currently open database in this work-area.

COPY STRUCTURE can be use to create a sub-set of the currently open database, based on a given field list.

COPY STRUCTURE command is preprocessed into __dbCopyStruct() function during compile time.

Examples

      // Create a new file that contains the same structure
       USE TEST
       COPY STRUCTURE TO MyCopy

       // Create a new file that contains part of the original structure
       USE TEST
       COPY STRUCTURE TO SomePart FIELDS name, address

Compliance

Clipper

Platforms

All

Seealso

COPY STRUCTURE EXTENDED, DBCREATE(), DBSTRUCT(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate(), __dbStructFilter()

__dbCreate()

Template

Function

Name

__dbCreate()

Category

API

Subcategory

Database

Oneliner

Create structure extended file or use one to create new file

Syntax

      __dbCreate( <cFileName>,  [<cFileFrom>],  [<cRDDName>],  ;
                  [<lNew>],  [<cAlias>] ) --> lUsed

Arguments

<cFileName> is the target file name to create and then open. (.dbf) is the default extension if none is given.

<cFileFrom> is an optional structure extended file name from which the target file <cFileName> is going to be built. If omitted, a new empty structure extended file with the name <cFileName> is created and opened in the current work-area.

<cRDDName> is RDD name to create target with. If omitted, the default RDD is used.

<lNew> is an optional logical expression, (.T.) opens the target file name <cFileName> in the next available unused work-area and makes it the current work-area. (.F.) opens the target file in the current
work-area. Default value is (.F.). The value of <lNew> is ignored if <cFileFrom> is not specified.

<cAlias> is an optional alias to USE the target file with. If not specified, alias is based on the root name of <cFileName>.

Returns

__dbCreate() returns (.T.) if there is database USED in the current work-area (this might be the newly selected work-area), or (.F.) if there is no database USED. Note that on success a (.T.) would be returned, but on failure you probably end up with a run-time error and not a (.F.) value.

Description

__dbCreate() works in two modes depending on the value of <cFileFrom>:

1) If <cFileFrom> is empty or not specified a new empty structure extended file with the name <cFileName> is created and then opened in the current work-area (<lNew> is ignored). The new
file has the following structure:

       Field name   Type   Length   Decimals
       ----------   ----   ------   --------
       FIELD_NAME   C      10        0
       FIELD_TYPE   C       1        0
       FIELD_LEN    N       3        0
       FIELD_DEC    N       3        0

The CREATE command is preprocessed into the __dbCopyStruct() function during compile time and uses this mode.

2) If <cFileFrom> is specified, it is opened and assumed to be a structure extended file where each record contains at least the following fields (in no particular order): FIELD_NAME, FIELD_TYPE,
FIELD_LEN and FIELD_DEC. Any other field is ignored. From this information the file <cFileName> is then created and opened in the current or new work-area (according to <lNew>), if this is a new work-area it becomes the current.

For prehistoric compatibility reasons, structure extended file Character fields which are longer than 255 characters should be treated in a special way by writing part of the length in the FIELD_DEC according to the following formula:

      FIELD->FIELD_DEC := Int( nLength / 256 )
      FIELD->FIELD_LEN := ( nLength % 256 )

CREATE FROM command is preprocessed into __dbCopyStruct() function during compile time and use this mode.

Examples

      // CREATE a new structure extended file,  append some records and
      // then CREATE FROM this file a new database file

      __dbCreate( "template" )
      dbAppend()
      FIELD->FIELD_NAME := "CHANNEL"
      FIELD->FIELD_TYPE := "N"
      FIELD->FIELD_LEN  := 2
      FIELD->FIELD_DEC  := 0
      dbAppend()
      FIELD->FIELD_NAME := "PROGRAM"
      FIELD->FIELD_TYPE := "C"
      FIELD->FIELD_LEN  := 20
      FIELD->FIELD_DEC  := 0
      dbAppend()
      FIELD->FIELD_NAME := "REVIEW"
      FIELD->FIELD_TYPE := "C"      // this field is 1000 char long
      FIELD->FIELD_LEN  := 232      // 1000 % 256 = 232
      FIELD->FIELD_DEC  := 3        // 1000 / 256 = 3
      dbCloseArea()
      __dbCreate( "TV_Guide",  "template" )

Compliance

Clipper

Platforms

All

Files

Library is rdd

Seealso

COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE, CREATE FROM, dbCreate(), dbStruct(), __dbCopyStruct(), __dbCopyXStruct()

__dbCopyXStruct()

Template

Function

Name

__dbCopyXStruct()

Category

API

Subcategory

Database

Oneliner

Copy current database structure into a definition file

Syntax

      __dbCopyXStruct( <cFileName> ) --> lSuccess

Arguments

<cFileName> is the name of target definition file to create. (.dbf) is the default extension if none is given.

Returns

__dbCopyXStruct() returns .F. if no database is USED in the current work-area, .T. on success, or a run-time error if the file create operation had failed.

Description

__dbCopyXStruct() create a new database named <cFileName> with a pre-defined structure (also called “structure extended file”):

       Field name   Type   Length   Decimals
       ----------   ----   ------   --------
       FIELD_NAME     C      10        0
       FIELD_TYPE     C       1        0
       FIELD_LEN      N       3        0
       FIELD_DEC      N       3        0

Each record in the new file contains information about one field in the original file. CREATE FROM could be used to create a database from the structure extended file.

For prehistoric compatibility reasons, Character fields which are longer than 255 characters are treated in a special way by writing part of the length in the FIELD_DEC according to the following formula (this is done internally):

      FIELD->FIELD_DEC := Int( nLength / 256 )
      FIELD->FIELD_LEN := ( nLength % 256 )

Later if you want to calculate the length of a field you can use the following formula:

      nLength := iif( FIELD->FIELD_TYPE == "C",  ;
                      FIELD->FIELD_DEC * 256 + FIELD->FIELD_LEN,  ;
                      FIELD->FIELD_LEN )

COPY STRUCTURE EXTENDED command is preprocessed into __dbCopyXStruct() function during compile time.

Examples

      // Open a database,  then copy its structure to a new file, 
      // Open the new file and list all its records
      USE Test
      __dbCopyXStruct( "TestStru" )
      USE TestStru
      LIST

Compliance

Clipper

Platforms

All

Files

Library is rdd

Seealso

COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE, CREATE FROM, dbCreate(), dbStruct(), __dbCopyStruct(), __dbCreate()

__dbCopyStruct()

Template

Procedure

Name

__dbCopyStruct()

Category

API

Subcategory

Database

Oneliner

Create a new database based on current database structure

Syntax

      __dbCopyStruct( <cFileName>,  [<aFieldList>] )

Arguments

<cFileName> is the name of the new database file to create. (.dbf) is the default extension if none is given.

<aFieldList> is an array where each element is a field name. Names could be specified as uppercase or lowercase.

Description

__dbCopyStruct() create a new empty database file with a structure that is based on the currently open database in this work-area. If <aFieldList> is empty, the newly created file would have the same structure as the currently open database. Else, the new file would contain only fields that exactly match <aFieldList>.

__dbCopyStruct() can be use to create a sub-set of the currently open database, based on a given field list.

COPY STRUCTURE command is preprocessed into __dbCopyStruct() function during compile time.

Examples

      // Create a new file that contain the same structure
      USE TEST
      __dbCopyStruct( "mycopy.dbf" )

      // Create a new file that contain part of the original structure
      LOCAL aList
      USE TEST
      aList := { "NAME" }
      __dbCopyStruct( "onlyname.dbf",  aList )

Compliance

Clipper

Platforms

All

Files

Library is rdd

Seealso

COPY STRUCTURE, COPY STRUCTURE EXTENDED, dbCreate(), dbStruct(), __dbCopyXStruct(), __dbCreate(), __dbStructFilter()

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

---

The secrets of array handling, part 1.

C5 Database Commands

Database Commands and Statements

APPEND BLANK : 

Add a new record to current database file.

APPEND BLANK

APPEND FROM :

Import records from a (.dbf) or ASCII file

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

AVERAGE :

Average numeric expressions in the current work area

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

CLEAR ALL* :

Close files and release public and private variables.

CLEAR ALL

CLOSE :

Close a specific set of files

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

COMMIT :

Perform a solid-disk write for all active work areas

COMMIT

CONTINUE :

Resume a pending LOCATE

CONTINUE

COPY STRUCTURE :

Copy the current (.dbf) structure to a new (.dbf) file

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

COPY STRUCTURE EXTENDED :

Copy field definitions to a (.dbf) file

COPY STRUCTURE EXTENDED TO <xcExtendedDatabase>

COPY TO :

Export records to a new (.dbf) or ASCII file

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

COUNT :

Tally records to a variable

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

CREATE :

Create an empty structure extended (.dbf) file

CREATE <xcExtendedDatabase>

CREATE FROM :

Create a new (.dbf) file from a structure extended file

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

DELETE :

Mark records for deletion

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

FIELD :

Declare database field names

FIELD <idField list> [IN <idAlias>]

FIND* :

Search an index for a specified key value

FIND <xcSearchString>

GO :

Move the record pointer to a specific record

GO[TO] <nRecord> | BOTTOM | TOP

JOIN :

Merge two (.dbf) files to create a new (.dbf) file

JOIN WITH <xcAlias> TO <xcDatabase>
     FOR <lCondition> 
     [FIELDS <idField list>]

LOCATE :

Search sequentially for a record matching a condition

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

PACK :

Remove deleted records from a database file

PACK

RECALL :

Restore records marked for deletion

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

REPLACE :

Assign new values to field variables

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

SEEK :

Search an index for a specified key value

SEEK <expSearch>

SELECT :

Change the current work area

SELECT <xnWorkArea> | <idAlias>

SET DELETED :

Toggle filtering of deleted records

SET DELETED on | OFF | <xlToggle>

SET EXCLUSIVE :

Establish shared or exclusive USE of database files

SET EXCLUSIVE ON | off | <xlToggle>

SET FILTER :

Hide records not meeting a condition

SET FILTER TO [<lCondition>]

SET  MEMOBLOCK :

     Change the block size for memo files

     SET MEMOBLOCK TO <nSize>

SET PATH :

Specify the search path for opening files

SET PATH TO [<xcPathspec list>]

SET RELATION :

Relate two work areas by a key value or record number

SET RELATION TO [<expKey> | <nRecord> INTO <xcAlias>]
    [, [TO] <expKey2> | <nRecord2> INTO <xcAlias2>...]
    [ADDITIVE]

SET SOFTSEEK :

Toggle relative SEEKing

SET SOFTSEEK on | OFF | <xlToggle>

SET UNIQUE :

Toggle the inclusion of nonunique keys into an index

SET UNIQUE on | OFF | <xlToggle>

SKIP :

Move the record pointer to a new position

SKIP [<nRecords>] [ALIAS <idAlias> | <nWorkArea>]

SORT :

Copy to a (.dbf) file in sorted order

SORT TO <xcDatabase> ON <idField> [/[A | D][C]]
    [, <idField2> [/[A | D][C]]...]
    [<scope>] 
    [WHILE <lCondition>] 
    [FOR <lCondition>]

SUM :

Sum numeric expressions to variables

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

TOTAL : 

Summarize records by key value to a (.dbf) file

TOTAL ON <expKey> FIELDS <idField list>
    TO <xcDatabase>
    [<scope>] 
    [WHILE <lCondition>] 
    [FOR <lCondition>]

UNLOCK :

Release file/record locks set by the current user

     UNLOCK [ALL]

UPDATE : 

Update current database file from another database file

UPDATE FROM <xcAlias>
   ON <expKey> [RANDOM]
   REPLACE <idField> WITH <exp>
   [, <idField2> WITH <exp2>...]

USE : 

Open an existing (.dbf) and its associated files

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

ZAP : 

Remove all records from the current database file

ZAP