|
How to: |
|
Reference: |
The REVISE command reads a stack of transaction data and writes it to a data source, inserting new segment instances and updating existing instances.
REVISE combines the functionality of the INCLUDE and UPDATE commands. It reads each stack row and processes each segment in the specified path using the following logic:
MATCH key ON MATCH UPDATE fields ON NOMATCH INCLUDE segment
You specify a path running from an anchor segment to a target segment. For each segment in the path, REVISE matches the instance of the segment in the stack against the corresponding instances in the data source. If the keys of an instance fail to find a match in the data source, REVISE adds the instance. If an instance does find a match, REVISE updates it using the fields that you have specified. The values that REVISE writes to the data source are provided by the stack.
Data source commands treat a unique segment as an extension of its parent, so that the unique fields seem to reside in the parent. Therefore, when REVISE adds an instance to a segment that has a unique child, it automatically also adds an instance of the child.
If the anchor segment is not the root, you must establish a current instance in each of the ancestor segments of the anchor, or provide ancestor segment key values in the source stack. This enables REVISE to navigate from the root to the first instance of the anchor segment.
The syntax of the REVISE command is
[FOR {int|ALL] REVISE data_spec [FROM stack [(row)]] [;]
where:
Indicates that an integer or ALL will be used to specify how many stack rows to write to the data source.
If you specify FOR, you must also specify a source stack using the FROM phrase. If you omit FOR, REVISE defaults to writing one row.
Is an integer expression that specifies the number of stack rows to write to the data source.
Specifies that all of the rows of the stack are to be written to the data source.
Identifies the path to be written to the data source and the fields to be updated:
If you have already identified the anchor and target segments in the process of specifying update fields, you do not need to do anything further to specify the path. Otherwise, if either the anchor or the target segment has not been identified using update fields, specify it using its segment name.
Indicates that the transaction data will be supplied by a stack. If this is omitted, the transaction data is supplied by the Current Area.
Is the name of the stack whose data is being written to the data source.
Is a subscript that specifies the first stack row to be written to the data source. If omitted, it defaults to 1.
Terminates the command. Although the semicolon is optional, you should include it to allow for flexible syntax and better processing. For more information about the semicolon, see Terminating a Command's Syntax.
In the following example the user is able to enter information for a new employee, or change the last name of an existing employee. Existing employee records are displayed in a grid. All of the information is stored in a stack named EmpStk.
MAINTAIN FILE EMPLOYEE FOR ALL NEXT Emp_ID INTO EmpStk; Winform Show GetData;
CASE Alter_Data FOR ALL REVISE Last_Name FROM EmpStk; ENDCASE
END
When the function Alter_Data is called from an event handler of a form, the REVISE command reads EmpStk and tries to find the Emp_ID of each row in the Employee data source. If Emp_ID exists in the data source, REVISE updates the Last_Name field of that segment instance. If it does not exist, then REVISE inserts a new EmpInfo instance into the data source, and writes the fields of EmpInfo from the stack to the new instance.
Maintain Data requires that the data sources to which it writes have unique keys.