INCLUDE

In this section:

How to:

Reference:

The INCLUDE command inserts segment instances from a transaction source (a stack or the Current Area) into a data source.

When you issue the command, you specify a path running from an anchor segment to a target segment. For each row in the transaction source, INCLUDE searches the data source for matching segment instances and, if none exist, writes the new instances from the transaction source to the data source.

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 ensures that INCLUDE can navigate from the root to the first instance of the anchor segment.

Syntax: How to Use the INCLUDE Command

The syntax of the INCLUDE command is 

[FOR {int|ALL}] INCLUDE path_spec [FROM stack[(row)]] [;]

where:

FOR

Is used with ALL or an integer to specify how many stack rows to add to the data source. If FOR is omitted, one stack row will be added.

When you specify FOR, you must also specify FROM to identify a source stack.

int

Is an integer constant or variable that indicates the number of stack rows to add to the data source.

ALL

Specifies that the entire stack is to be added to the data source.

path_spec

Identifies the path to be added to the data source. To identify a path, specify its anchor and target segments. You cannot specify a unique segment as the anchor. If the path contains only one segment, and the anchor and target are identical, simply specify the segment once. For paths with multiple segments, to make the source code clearer to readers, you can also specify segments between the anchor and target.

To add a unique segment instance to a data source, you must explicitly specify the segment in path_spec. Otherwise, the unique segment instance will not be added even if it is on the path between the anchor and target segments. This preserves the advantage of assigning space for a unique segment instance only when the instance is needed.

To specify a segment, provide the name of the segment or of a field within the segment.

FROM

Is used to specify a stack containing records to insert. If no stack is specified, data from the Current Area is used.

stack

Is a stack name. Only one stack can be specified.

row

Is a subscript that specifies the first stack row to add to the data source.

;

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 semicolon, see Terminating a Command's Syntax.

Example: Adding Data From Multiple Stack Rows

The following example tries to add the data in rows 2, 3, and 4 of Stkemp into the data source. The stack subscript instructs the system to start in the second row of the stack. The FOR 3 instructs the system to INCLUDE the next three rows. 

FOR 3 INCLUDE Emp_ID FROM Stkemp(2);

Example: Preventing Duplicate Records

You can execute the INCLUDE command after a MATCH command that fails to find a matching record. For example: 

MATCH Emp_ID FROM Newemp;
ON NOMATCH INCLUDE Emp_ID FROM Newemp;

The INCLUDE command can also be issued without a preceding MATCH. In this situation, the key field values are taken from the source stack or Current Area and a MATCH is performed internally. When a set of rows is input without a prior confirmation that it does not already exist in the data source, one or more of the rows in the stack may be rejected. Upon the first rejection, the process stops and the rest of the set is rejected. For all of the rows to be accepted or rejected as a unit, the set should be treated as a logical unit of work and a ROLLBACK issued if the entire set was not accepted. After an INCLUDE, the transaction variable FocError is given a value. If the INCLUDE is successful, FocError is zero (0). If the INCLUDE fails (for example, if the key values already exist in the data source), Maintain Data assigns a non-zero value to FocError, and (if the include was set-based) assigns the value of the row that failed to FocErrorRow. If at COMMIT time there is a concurrency conflict, Maintain Data sets FocCurrent to a non-zero value.

Example: Adding Multiple Segments

This example shows how data is added from two segments in the same path. The data comes from a stack named EmpInfo and the entire stack is used. When the INCLUDE is complete, the variable FocError is checked to see if the INCLUDE was successful. If it failed, a general error handling function is called: 

FOR ALL INCLUDE Emp_ID Dat_Inc FROM EmpInfo;
IF FocError NE 0 THEN PERFORM Errhandle;

Example: Adding Data From the Current Area

The user is prompted for the employee ID and name. The data is included if it does not already exist in the data source. If the data already exists, it is not included, and the variable FocError is set to a non-zero value. Since the procedure does not check FocError, no error handling takes place and the user does not know whether or not the data is added: 

NEXT Emp_ID Last_Name First_Name;
INCLUDE Emp_ID;

Reference: Usage Notes for INCLUDE

  • If there is a FOR prefix, a stack must be mentioned in the FROM phrase.
  • When an INCLUDE command is complete, the variable FocError is set. If the INCLUDE is successful (the records to be added do not exist in the data source), then FocError is set to zero (0). If the records do exist, FocError is set to a non-zero value, and (if it is a set-based INCLUDE) FocErrorRow is set to the number of the row that failed.
  • Maintain Data requires that data sources to which it writes have unique keys.

Reference: Commands Related to INCLUDE

  • COMMIT. Makes permanent all data source changes since the last COMMIT.
  • ROLLBACK. Cancels all data source changes made since the last COMMIT.

Data Source Position

A Maintain Data procedure always has a position either within a segment or just prior to the first segment instance. If data has been retrieved, the position is the last record successfully retrieved on that segment. If a retrieval operation fails, the data source position remains unchanged.

If an INCLUDE is successful, the data source position is changed to the new record. On the other hand, if the INCLUDE fails, it might be because there is already a record in the data source with the same keys. In this case, the attempted retrieval prior to the INCLUDE is successful, and the position is on that record. Therefore, the position in the data source changes.

Null Values

If you add a segment instance that contains fields for which no data has been provided, and those fields have been defined in the Master File with the MISSING attribute, they are assigned a null value. If those fields have been defined in the Master File without the MISSING attribute, they are assigned a default value of a space for character and date and time fields, or zero (0) for numeric fields.