table.APPEND Function
Syntax
Arguments
- Append.t_db
CTransaction table filename
- Append.type
CAppend type. There are three types of Append operations. The append.type parameter has the following possible values:"All""Unique Only""Unique, Replace Existing"
- Append.convert_types
LSpecifies if data should be converted to match the data type of the target field. For example, if you are appending a time value into a date field, and this flag is set to .T., then the data will be automatically converted. By default, this flag is set to .F., which means that if you try to append data into a field of the wrong data type, an error will occur.
- Append.m_key
CMaster Key Expression. Required when you use either Unique Only or Unique, Replace Existing. A key expression is a field or combination of fields that Alpha Anywhere uses to determine which table records are considered unique.
- Append.t_key
CTransaction Key Expression. Required when you use either Unique Only or Unique, Replace Existing. A key expression is a field or combination of fields that Alpha Anywhere uses to determine which table records are considered unique.
- Append.m_filter
CEOptional. A character filter expression that evaluates to a logical value. The Master Filter is used with either the Unique Only or the Unique, Replace Existing operation. Only the subset of Master records that pass through this filter are used when searching for existing records.
- Append.t_filter
CEOptional. A character filter expression that evaluates to a logical value. The Transaction Filter indicates how many fields are to be appended. Determines which records from the Transaction table are appended.
- Append.m_count
NNumber of Master Mappings. Indicates how many fields are to be appended. Required when the Master and Transaction tables have different structures. You must map fields explicitly so that the correct values are copied from the Transaction table fields and entered in the Master table fields. Transaction table fields not mapped to the Master table are not transferred during the Append operation. Each field mapping is expressed through a group of three parameters:Case (optional)Master FieldMaster Expression
- Append.m_case1
C Required for each field when Append.type is "Unique, Replace Existing". The Master Case parameter specifies three possible mapping types: "Either" - The Transaction record is either appended or used to replace a Master record. "Appended" - The Transaction record is appended. "Replaced" - The Transaction record matches a Master table record and replaces that record.
- Append.m_field1
C Master Field1 ... Master FieldN. The name of the Master Field in <TBL> to which data is to be appended.
- Append.m_exp1
CMaster Expression1...Master ExpressionN. Contains the value, field, or expression that is to be assigned to the Master Field. Field names from the transaction table must have an "@" in front of the table or alias name.
- ... an arbitrary number of fields
- Append.m_caseN
CRefer to append.m_case1
- Append.m_fieldN
CRefer to append.m_field1
- Append.m_expN
CRefer to append.m_exp1
- Append.t_count
NNumber of Transaction Mappings (M). Refers to how many fields in the Transaction table are to be updated. as in the Master mapping, each transaction mapping is expressed through a group of three parameters. Refer to Append_m_count.
- Append.t_case1
COptional. The Transaction Case specifies four possible situations that may occur when the append operation is attempted. When you specify a case, you enable an update of the Transaction table, which might be useful for recording the status of the append operation. The Transaction Case specifies four possible types of operations:"Appended""Replaced""Either" (appended or replaced)"Violated" (the append failed for this record).
- Append.t_field1
CA field in the Transaction table.
- Append.t_exp1
CAn expression that assigns a value to t_field1.
- Append.t_caseM
CRefer to append.t_case1.
- Append.t_fieldM
C Refer to append.t_field1.
- Append.t_expM
C Refer to append.t_exp1.
Description
Append the records of one table to another, optional argument provides a quick way to append records of exact same table structure. Specify the required values in the Append dot variable, then use the following command: <TBL>.APPEND()
Discussion
The <TBL>.APPEND() method is a high-level utility function used to append the records of one table to another. Most parameters passed to <TBL>.APPEND()through the append function variable correspond directly with the prompts in the Append Records operation called by clicking Operations > New > Append Records.
You perform the Append operation by selecting a Transaction table ( append.t_db ) and a Master table (<TBL>). The Transaction table is the source table that supplies the records; the Master table is the target table.
The Number of Transaction Mappings refers to how many fields in the Transaction table are to be updated. as in the Master mapping, each transaction mapping is expressed through a group of three parameters.
This script zaps the records in the current table and then appends new records to the table from the specified Transaction table.
Example
dim tbl as P
dim filename as C
dim basename as C
filename = "c:\a5\data\cust_new.dbf"
basename = "@cust_new"
tbl = table.current()
tbl.zap(.T.)
append.t_db = filename
append.m_key = ""
append.t_key = ""
append.m_filter = ""
append.t_filter = ""
append.type = "All"
append.m_count = 9
append.m_field1 = "CUST_ID"
append.m_exp1 = basename + "->CUST_ID"
append.m_field2 = "SALUTATION"
append.m_exp2 = basename + "->SALUTATION"
append.m_field3 = "FIRST_NAME"
append.m_exp3 = basename + "->FIRST_NAME"
append.m_field4 = "LAST_NAME"
append.m_exp4 = basename + "->LAST_NAME"
append.m_field5 = "ADDRESS_1"
append.m_exp5 = basename + "->ADDRESS_1"
append.m_field6 = "ADDRESS_2"
append.m_exp6 = basename + "->ADDRESS_2"
append.m_field7 = "CITY"
append.m_exp7 = basename + "->CITY"
append.m_field8 = "STATE_PROV"
append.m_exp8 = basename + "->STATE_PROV"
append.m_field9 = "ZIP"
append.m_exp9 = basename + "->ZIP"
append.t_count = 0
tbl.append()
ui_msg_box("Note", "Operation Completed")See Also