In this section:

How to:


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.

Top of page

Syntax: How to Use the INCLUDE Command

The syntax of the INCLUDE command is

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



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.


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


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


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, if you wish 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.


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


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


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 Command 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:


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. If the INCLUDE fails (for example, if the key values already exist in the data source), Maintain 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 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:

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;

Top of page

Reference: Usage Notes for INCLUDE

Top of page

Reference: Commands Related to INCLUDE

Top of page

Data Source Position

A Maintain 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.

Top of page

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 (for numeric fields).