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.

          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

Seealso

APPEND FROM, COPY FILE, COPY STRUCTURE, SET DELETED

Advertisements

CREATE FROM

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

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

 

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