|
In this section: |
|
How to: |
|
Reference: |
The MATCH command enables you to identify and retrieve a single segment instance or path instance by key value. You provide the key value using a stack or the Current Area. MATCH finds the first instance in the segment chain that has that key.
You specify which path to retrieve by identifying its anchor and target segments. If the anchor segment is not the root, you must establish a current instance in each of the ancestor segments of the anchor. This enables MATCH to navigate from the root to the anchor segment instance.
The command always matches on the full key. To match on a partial key, use the NEXT command and identify the value of the partial key in the WHERE phrase of the command.
If the data source has been defined without a key, you can retrieve a segment instance or path using the NEXT command, and identify the desired instance using the WHERE phrase of the command.
The syntax of the MATCH command is
MATCH path_spec [FROM stack[(row)]] [INTO stack[(row)]] [;]
where:
Identifies the path to be read from the data source. To identify a path, specify its anchor and target segments. If the path contains only one segment, the anchor and target are identical. Specify the segment once. For paths with multiple segments, to make the code clearer to readers, you can also specify segments between the anchor and target.
To specify a segment, provide the name of the segment or of a field within the segment.
Is used to specify a stack containing a key value on which to match. If you omit this, Maintain Data uses a value in the Current Area. In either case, the columns containing the key value must have the same names as the corresponding key fields in the data source.
Is used to specify the stack that the data source values are to be placed into. Values retrieved by MATCH are placed into the Current Area when an INTO stack is not supplied.
Is a stack name. Only one stack can be specified for each FROM or INTO phrase. The stack name should have a subscript specifying which row is to be used. If a stack is not specified, the values retrieved by the MATCH go into the Current Area.
Is a subscript that specifies which row is used. The first row in the stack is matched against the data source if the FROM stack does not have a subscript. The data is placed in the first row in the stack if the INTO stack does not have a subscript.
Terminates the command. Although the semicolon is optional, it is recommended that you include it to allow for flexible syntax and better processing. For more information about the benefits of including the semicolon, see Terminating a Command's Syntax.
The following example performs a MATCH on the key field in the PayInfo segment. It gets the value for Pay_Date from the Pay_Date field, which is in the Current Area. After the match is found, all of the field values in the PayInfo segment are copied from the data source into the Current Area:
MATCH Pay_Date;
The next example shows a MATCH on the key in the EmpInfo segment. It gets the value for Emp_ID from the Emp_ID column in the Cnt row of the Stackemp stack. After the match is found, all of the fields in the EmpInfo segment are copied into the Current Area:
MATCH Emp_ID FROM Stackemp(Cnt);
The last example is the same as the previous example except that an output stack is mentioned. The only difference in execution is that after the match is found, all of the fields in the EmpInfo segment are copied into a specific row of a stack rather than into the Current Area:
MATCH Emp_ID FROM Stackemp(Cnt) INTO Empout(Cnt);
When a MATCH command is issued, Maintain Data tries to retrieve a corresponding record from the data source. If there is no corresponding value and an ON NOMATCH command follows, the command is executed.
The MATCH command looks through the entire segment to find a match. The NEXT command with a WHERE qualifier also locates a data source record, but does it as a forward search. That is to say, it starts at its current position and moves forward. It is not an exhaustive search unless positioned at the start of a segment. This can always be done with the REPOSITION command. A MATCH is equivalent to a REPOSITION on the segment followed by a NEXT command with a WHERE phrase specifying the key. If any type of test other than the equality test that the MATCH command provides is needed, the NEXT command should be used.