REVISE

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.

Syntax: How to Use the REVISE Command

The syntax of the REVISE command is

[FOR {int|ALL] REVISE data_spec [FROM stack [(row)]] [;]

where:

FOR

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.

int

Is an integer expression that specifies the number of stack rows to write to the data source.

ALL

Specifies that all of the rows of the stack are to be written to the data source.

data_spec

Identifies the path to be written to the data source and the fields to be updated:

  1. Specify each field that you want to update in existing segment instances. You can update only non-key fields. Because a key uniquely identifies an instance, keys can be added and deleted but not changed.
  2. Specify the path by identifying its anchor and target segments. You can specify a segment by providing its name or the name of one of its non-key fields.

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.

FROM

Indicates that the transaction data will be supplied by a stack. If this is omitted, the transaction data is supplied by the Current Area.

stack

Is the name of the stack whose data is being written to the data source.

row

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.

Example: Using REVISE

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.

Reference: Usage Notes for REVISE

Maintain Data requires that the data sources to which it writes have unique keys.

Reference: Commands Related to REVISE

  • INCLUDE. Adds new segment instances to a data source.
  • UPDATE. Updates data source fields.
  • COMMIT. Makes all data source changes since the last COMMIT permanent.
  • ROLLBACK. Cancels all data source changes made since the last COMMIT.