Skip to content

Copy_Records

See Also: Implementing Callback Functions, Copy_DB, DF_RUNTIME_PROGRESS_FREQUENCY

Purpose

The Copy_Records command is used to copy records from one database table to another.

Syntax

Copy_Records {from-table-number} To {to-table-number} [{num-records}] ;
[Using {index-num}] ;
[Callback {callback-object}]

Argument Explanation

  • {from-table-number}: The filelist number of the database table from which records are to be copied.

  • {to-table-number}: The filelist number of the destination database table to which records are to be copied.

  • {num-records}: The maximum number of records to be copied. If this parameter is not specified, all records will be copied. A value of 0 will also copy all records.

  • {index-num}: The index that will be used to determine the order of the records to be copied. If not specified, records are copied in the order of recnum.

  • {callback-object}: A handle to an object that will receive the Callback message during the sort operation. Refer to Implementing Callback Functions for more information.

What It Does

Copy_Records copies {num-records} records from {from-table-number} to {to-table-number}. If the Using parameter is used, records are copied using the specified {index-num}. If not, then recnum is used. If any copied record contains a field value matching the value in any other record and the field participates in an online unique index, Error 28 "Duplicate records not allowed in table" will be returned, and the record will not be copied.

This command copies record data between database tables of the same or different types and/or structures. Data is copied from each field in the source table for which a field of the same name exists in the target table. Other than name, the fields do not have to have the same size or type attributes, since data conversions will take place automatically.

Data may be truncated in the destination table if the target field is not large enough to contain all of the converted data. Additionally, when converting an ASCII, text, or binary field to a numeric or date field, the target field will contain a zero if the source field was not a valid number or date as required.

If the record buffer of the {from-table-number} table is active, the copy starts from the active record and proceeds until {num-records} records have been copied to the target table. If the record buffer of the source table is inactive, the copy starts at the first record (based on {index-num}) in the source table.

If {num-records} is zero, all records from the starting point to the end of the source table will be copied. If {num-records} is greater than the number of records from the starting point to the end of the source table, only the records from the starting point to the end will be copied.

After each record is copied, the callback function (if specified) will be called and passed a string containing the number of records copied.

Example

Object oCopyRecords is a Array
    Function Callback String sText Integer iLogicalID Returns Integer
        Showln sText
        // Tell operation to continue
        Function_Return False
    End_Function

    Procedure DoRecordCopy
        // This is needed to return a callback for each record
        Set_Attribute DF_RUNTIME_PROGRESS_FREQUENCY to 1
        Copy_Records Prospect.File_Number To Customer.File_Number ;
            0 Callback Self
    End_Procedure
End_Object

If the record buffer of Prospect is inactive when Procedure DoRecordCopy is called, all records in Prospect will be copied to Customer, in recnum order. Note that only fields with the same name in both tables get copied.

Notes

  • Instead of the index number to find by, {index-num} can be a negative field number. This signifies that the index to be used for the source table is the main index of that field. For example, if {index-num} is -5, the main index of the fifth field will be used for copying the records.

  • Upon successful completion, the source and target table record buffers will contain the last record copied.

  • If {num-records} is 0, all records will be copied.

  • The destination table does not have to contain all the fields that the source table does; whichever ones it has will be copied.

  • The callback message is sent each time the number of records in the global attribute DF_RUNTIME_PROGRESS_FREQUENCY is copied, with parameters indicating the number of records copied and the total number of records to be copied.