Home   :   Matrix Language   :   Pattern Statements   :   Include Statements

Include Statements

Statements

SystemInclude

MatrixInclude

SiloInclude

RealmInclude

DomainInclude

EntityInclude

StateInclude

ActionInclude

ProcessDomainInclude

ProcessEntityInclude

General

The set of include statements allows model code to be partitioned into separate sections corresponding to whatever is most convenient, which is typically determined by the size of the model.

The included code is held in text files within a defined folder structure which the Model Compiler creates automatically. The folder structure varies according to the structure of the model.

At model compilation time the code section is included in the model as if it had been written in place. There is no concept of invoking or calling the included code sections. Include files do not take parameters but like other statements they do rely on context.

In the text file, a define include statement signals the start of the included section of code. Only whole statement regions are allowed to be held in include files. Define pocess include sections may include other include statements which may be included recursively.

In compliance with the Matrix design philosophy, a single include statement may include one or more include sections in the statement's subregion. The file containing the included section must have the same name as its entry in the listing.

The main Matrix System script, System.matrix (name not optional), is held in the following folder:

M:\Matrix\Models\<Model_Name>\$Main

Associated Statements

The Include statements are used with the following define include statements:

DefineSystemInclude

DefineMatrixInclude

DefineSiloInclude

DefineRealmInclude

DefineDomainInclude

DefineEntityInclude

DefineStateInclude

DefineActionInclude

DefineDomainProcessInclude

DefineEntityProcessInclude

For example, the named SystemInclude statement includes the statements specified by the similarly named DefineSystemInclude statement subregion.

SystemInclude Statement

System:Passenger_Elevator

SystemInclude

Description

Types

ModelApplication

The SystemInclude statement lists one or more code sections that are to be included from text files.

System level include files are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\01System

MatrixInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

MatrixInclude

Description

SiloM1SoftwareApplication

SiloM0RealWorldObjects

The MatrixInclude statement lists one or more code sections that are to be included from text files.

Matrix level include files are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\02Matrix

SiloInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

Silo:M1:Software_Application

SiloInclude

Description

Types

RealmAnalysisOfApplication

The SiloInclude statement lists one or more code sections that are to be included from text files.

Silo level include files are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\03Silo

RealmInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

Silo:M1:Software_Application

Realm:Analysis_Of_Application

RealmInclude

Description

ElevatorManagement

The RealmInclude statement lists one or more code sections that are to be included from text files.

Realm level include files are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\04Realm

DomainInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

Silo:M1:Software_Application

Realm:Analysis_Of_Application

Domain:Elevator_Management

DomainInclude

Event_Context

Floor

Door

Car_Service

Car_Stop

Service_Assigner

Car

The DomainInclude statement lists one or more code sections that are to be included from text files.

Domain level include files are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\Elevator_Management\$Main

EntityInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

Silo:M1:Software_Application

Realm:Analysis_Of_Application

Domain:Elevator_Management

Entity:Car

EntityInclude

Attributes

Relationships

States

The EntityInclude statement lists one or more code sections that are to be included from text files.

Entity level include files are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\Elevator_Management\Car\$Main

StateInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

Silo:M1:Software_Application

Realm:Analysis_Of_Application

Domain:Elevator_Management

Entity:Car

State

StateInclude

Dataset

Stationary

SelectingSchedule

ServicingSchedule

Moving

CheckingSchedule

Slowing

Opening

Accessible

Closing

The StateInclude statement lists one or more code sections that are to be included from text files.

State level include files are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\Elevator_Management\Car\01State\$Main

ActionInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

Silo:M1:Software_Application

Realm:Analysis_Of_Application

Domain:Elevator_Management

Entity:Car

State

DynamicState:Stationary

ActionInclude

StateAction

Transitions

The ActionInclude statement lists one or more code sections that are to be included from text files.

Action level include files are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\Elevator_Management\Car\01State\Stationary

ProcessDomainInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

Silo:M1:Software_Application

Realm:Analysis_Of_Application

Domain:Elevator_Management

Entity:Car

State

DynamicState:Stationary

StateAction

ProcessDomainInclude

Find_Next_Floor

The ProcessDomainInclude statement lists one or more code sections that are to be included from text files and which are common across entities or belong to no entity.

Many domain based includes can be specified in a single ProcessDomainInclude statement. The Model Compiler will only search for files in the domain process files folder.

DefineDomainProcessInclude code sections may include other ProcessDomainInclude and ProcessEntityInclude statements. When traversing reflective relationships it can often be useful to use a process include statement recursively as an alternative to the more formal and perhaps correct way using events.

Typically, Model Compilers will generate a DefineDomainProcessInclude code section as a procedure if it is included more than once or if it is used recursively. If it is only used once then the code section is simply generated inline. This is usually the default configuration for Model Compilers but an option to generate all process include code sections as procedures is usually provided.

Domain process level include files that are to be shared between all entities in a domain are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\Elevator_Management\01Process

ProcessEntityInclude Statement

System:Passenger_Elevator

Matrix:Model:Application

Silo:M1:Software_Application

Realm:Analysis_Of_Application

Domain:Elevator_Management

Entity:Car

State

DynamicState:Stationary

StateAction

ProcessEntityInclude

Car : Main_Traverse

The ProcessEntityInclude statement lists one or more code sections that are to be included from text files and that are belong to single entity.

Many entity based includes can be specified in a single ProcessEntityInclude statement. The Model Compiler will only search for files in the entity process files folder.

DefineEntityProcessInclude code sections may include other ProcessEntityInclude and ProcessDomainInclude statements. When traversing reflective relationships it can often be useful to use a process include statement recursively as an alternative to the more formal and perhaps correct way using events.

Typically, Model Compilers will generate a DefineEntityProcessInclude code section as a procedure if it is included more than once or if it is used recursively. If it is only used once then the code section is simply generated inline. This is usually the default configuration for Model Compilers but an option to generate all process include code sections as procedures is usually provided.

Entity process level include files that belong to a single entity are held in the following folder:

M:\Matrix\Models\Passenger_Elevator\Elevator_Management\Car\02Process

Include Folder Structure

The include folder structure is best shown by example. Below is the file structure for the Professional Edition of the Passenger Elevator mode:

Passenger_Elevator

$Main                               Main Script

01System                            System Includes

02Matrix                            Matrix Includes

03Silo                              Silo Includes

04Realm                             Realm Includes

Elevator_Management

$Main                           Domain Includes

01Process                       Process Domain Includes

Car

$Main                       Entity Includes

01State

$Main                   State Includes

Accessible              Action Includes

Checking_Schedule       Action Includes

Closing                 Action Includes

Moving                  Action Includes

Opening                 Action Includes

Selecting_Schedule      Action Includes

Servicing_Schedule      Action Includes

Slowing                 Action Includes

Stationary              Action Includes

02Process                   Process Entity Includes

Car_Service

$Main                       Entity Includes

...

Car_Stop

$Main                       Entity Includes

...

Door

$Main                       Entity Includes

...

Floor

$Main                       Entity Includes

...

Service_Assigner

$Main                       Entity Includes

...

Folders either contain other folders or they contain only files. Shown below are the typical files that can be expected to be found in the various folders for the Passenger Elevator model:

Passenger_Elevator

$Main

System.matrix

01System

Description.matrix

Types.matrix

ModelApplication.matrix

02Matrix

Description.matrix

Types.matrix

SiloM1SoftwareApplication.matrix

SiloM0RealWorldObjects.matrix

03Silo

Description.matrix

Types.matrix

RealmAnalysisOfApplication.matrix

04Realm

Description.matrix

Types.matrix

ElevatorManagement.matrix

Elevator_Management

$Main

Description.matrix

Types.matrix

EventContext.matrix

Car.matrix

CarService.matrix

CarStop.matrix

Door.matrix

Floor.matrix

ServiceAssigner.matrix

01Process

Domain_CreateCarStop.matrix

Domain_RelationshipUnrelate.matrix

Domain_Void.matrix

Car

$Main

Attributes.matrix

Relationship.matrix

States.matrix

01State

$Main

Datasets.matrix

Stationary.matrix

SelectingSchedule.matrix

ServicingSchedule.matrix

Moving.matrix

CheckingSchedule.matrix

Slowing.matrix

Opening.matrix

Accessible.matrix

Closing.matrix

Accessible

...

Checking_Schedule

...

Closing

...

Moving

...

Opening

...

Selecting_Schedule

...

Servicing_Schedule

...

Slowing

...

Stationary

StateAction.matrix

Transitions.matrix

02Process

Entity_MainTraverse.matrix

Entity_GenerateServiceRequested.matrix

Entity_FindScheduleFloor.matrix

Car_Service

...

Car_Stop

...

Door

...

Floor

...

Service_Assigner

...

Include Statement Example

The example below shows the Passenger Elevator demonstration model down to the domain and entity level. The DomainInclude statement simply lists the entities which belong in Elevator Management domain.

System:Passenger_Elevator

SystemInclude

Description

Type

Matrix:Model:Application

Silo:M1:Software_Application

Realm:Analysis_Of_Application

Domain:Elevator_Management

DomainInclude

Event_Context

Floor

Door

Car_Service

Car_Stop

Service_Assigner

Car

MatrixInclude

SiloM0RealWorldObjects

The code fragment below shows the contents of the DefineDomainInclude Car include file referenced in the list above. The DefineDomainInclude must be the first statement and names both the include code fragment and the include file.

Similarly, the StateInclude statement enables the detailed description of each state to appear in its own file while appearing as a member of a list at this level.

DefineDomainInclude:Car

Entity:Car

Attribute

Direction : Direction

Relationship

Services                  ->> Car_Service

Currently_at              --> Floor

Accessed_through          --> Door

Scheduled_to_move_up_to   |>> Floor

Scheduled_to_move_down_to |>> Floor

State

Dataset:Travel

Floor : Next_floor_number

StateInclude

Stationary

Selecting_Schedule

Servicing_Schedule

Moving

Checking_Schedule

Slowing

Opening

Accessible

Closing

The next DefineStateInclude describes the Checking Schedule state for the Car entity. The StateAction statement lists out the actual work to be performed on entry to the state in response to an event.

There are three process level actions to perform, the last one of which is the ProcessEntityInclude statement that enables further process actions to be listed in another file that can be included elsewhere in the model.

DefineStateInclude:Checking_Schedule

DynamicDataState:Checking_Schedule:Travel

ProcessData

Flag : stop_not_found

StateAction

Assignment

SetBoolean

stop_not_found := <<True>>

Traverse

Navigation

Car : Currently_at : Floor

TraverseSelection

Unrelate

Car : Currently_at : Floor

ProcessEntityInclude

Car : Check_Floor_Schedule

Transition

EventState

Continue           -> Moving

Stop_at_next_floor -> Slowing

IgnoreEvent

Service_requested

Open_door

Close_door

CannotHappen

Service_schedule

Service_current_floor

Moving

Floor_approaching

Car_stopped

Door_open

Door_closed

The first part of the DefineEntityProcessInclude file for Check Floor Schedule is shown below:

DefineEntityProcessInclude:Car:Check_Floor_Schedule

| Find all floors.

Traverse

Navigation

Car         : Services : Car_Service

Car_Service : Services : Floor

TraverseSelection

| Set car's current floor.

CaseSelection

WhenCase

ConditionAnd

TestAnd

Floor.Number == Next_floor_number

WhenCaseSelection

Relate

Car : Currently_at : Floor

...