Introduction

Modules are used extensively in CAST Imaging and CAST Dashboards as a means to configure analysis results into meaningful groups or sets for display purposes:

Indeed, objects that are not part of a module:

• cannot be seen in CAST Imaging/CAST Dashboards
• cannot be included in Architecture Models
• cannot be included in Transaction/Function Point configurations

The definition of modules within applications also impacts the accessibility and usability of application assessment results. Specifically, in the CAST quality and quantity model, the module is the smallest assessment entity. The definition of a module can improve the relevance of the analysis results by linking modules to development teams and application functional layers etc. See also Defining consolidation weighting settings for more information.

The content of a module is based on source code. CAST offers various automatic module strategies for display of source code, as follows (see Auto Generate below for more information about each strategy):

• Console ≥ 2.8 when using onboarding with Fast Scan: "Full content"
• Console ≥ 2.8 when using onboarding without Fast Scan: "per Technology"
• Console 2.0 - 2.7 all onboarding modes: "per Technology"
• Console 1.x: "per Technology"

These automatic module strategies can be modified once a Version has been set as the current version (onboarding without Fast Scan) or an initial deep analysis has been completed (onboarding with Fast Scan) using the Modules configuration options shown below:

Click to enlarge

Changes made

Any changes made in the Modules configuration page (e.g. changing the module configuration) will cause a banner to appear at the top:

This indicates that the changes you have made will impact your analysis results and therefore that the data that is used for the Architecture Studio, Transaction configuration and upload to CAST Imaging will not be up-to-date. Clicking the Update button in the banner will run a special step called Prepare analysis data that should complete relatively quickly (more quickly than a full analysis or snapshot) and ensures that the data used by the Architecture Studio, Transaction configuration and upload to CAST Imaging is up-to-date based on the changes you have made. 

This step is always actioned when you either run an analysis (without a snapshot) or generate a new snapshot. When the Prepare analysis data step is complete, the banner will no longer be displayed.

Auto Generate

The Auto Generate option enables you to change the automatic module strategy chosen for your Application.  These modules will only be created when you run a new analysis, therefore you cannot view them in this list until the analysis has completed.

Error: Internal error occurred. 
Return value: 1000 
  The application is closing. Call CAST support now providing the log file at \AipNode\data\logs\external_logs\c7ea2ce1-77bb-4492-ae85-7342be6a1f48\analyze\analyze-20200722-152438.txt 
  Source Server / My_APP: Missing Generate one module per : 
  Source Server / my_APP: Missing User Defined Modules

Changing the module strategy

If you make a change to the module strategy, you will need to run a new analysis in order for the changes to be taken into account - if you want the modules to be visible in the CAST dashboards, then a snapshot will also need to be generated. Remember that:

• any existing modules created by another automatic strategy will be retained and the modules from the newly selected automatic strategy will be created at the start of the analysis/snapshot generation process. This behaviour is in contrast to the behaviour in previous releases of Console (≤ 1.17) where existing modules were deleted.
• changing strategy will impact existing results in the CAST Dashboards/CAST Imaging.
• choosing None (Manual Creation) for the automatic strategy means that you must create at least one User Defined module or have at least one Module listed in the list of modules, otherwise the analysis/snapshot will fail.

User Defined Modules

In addition to automatic strategy modules, Console offers you the option to create User Defined Modules - these Modules can be configured to contain the exact content you require for display in the CAST Dashboards. Content is configured using:

• a Filter on your analysis results, either:
  • via the GUI creating an Object Filter (using the Technology, Analysis Units and Object Names filter criteria combination) in order to define the content you require. Certain rules are applicable for User Defined Modules created using an Object Filter::
    • you can add multiple Object Filters per User Defined Module
    • you can choose only one Technology (the drop down will show the technologies found in your application source code)
    • when you have chosen the Technology, the analysis units list will show only analysis units belonging to the selected technology
    • if you do not choose a Technology, the analysis unit list will show all available analysis units in your application
    • you can select multiple analysis units
    • you can add multiple Object Name patterns: the filter result includes all the results of the all the name patterns you have added
    • the Object Name pattern choices are Name, Full Name or Path, with operators Equals, Like or Match
  • via the GUI creating an Explicit Filter using an SQL query
• Module per Technology
• Module per Analysis Unit
• Module per Subfolder

Add a User Defined Module

To add a User Defined Module, first change the auto strategy to either of the following (when the auto strategy is set to any other option, it is not possible to create user defined modules):

• None (Manual Creation)
• Unassigned (recommended)

The Add button should now be enabled - click it and choose the option you require:

Click to enlarge

Each option is explained below:

Module - based on a custom Filter

This option allows you to create a module using a custom Filter. You can create:

• multiple Object Filters via the GUI
• a single Explicit Filter using a SQL query
• a combination of either

Object Filter

The Object Filter screen will be displayed:

Module Name	Choose a name for the User Defined Module (the name you give to a User Defined Module will form the name of the Module in the CAST Dashboards). The name of the Module should only use the following permitted characters - any unauthorized characters will result in an error message: 0123456789 abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
Description	Free text field allowing you to create a description for this module. This description will be displayed in the Description column in the module list:
Filter Name	You can include as many filters as required - enter a name for each Object Filter, or leave as default.
Technology Selection	Click the drop down list box to choose a Technology to filter on - the list of available technologies results from the most recent source code delivery (you do not need to have run an analysis). All subsequent options in the filter will then be restricted to this Technology. It is not obligatory to select a Technology: if you do not restrict the Technology to one specific technology, then all subsequent options will also not be restricted.
Analysis Unit Selection	Click Add to choose an Analysis Unit to filter on - the list of Analysis Units results from the most recent source code delivery (you do not need to have run an analysis) will be displayed. All subsequent options in the filter will then be restricted to the chosen Analysis Unit(s). It is not obligatory to select an Analysis Unit: if you do not restrict the Analysis Unit, then all subsequent options will not be restricted. Use the "+" icon to select the Analysis Unit(s) you want to filter on: A new dialog box will open allow you to select the Analysis Unit(s) - tick the items you want as shown below. This dialog shows all available Analysis Units in the current delivery - by default all Analysis Units will be displayed, even those that are already used in other Modules (the Modules column lists the existing Modules which the Analysis Unit is used in). You can also enable the Show only not used option if you only want to see Analysis Units that are not already used in existing modules: Selected Analysis Units will automatically appear in the filter:
Object Name Selection	Click to Add to create a new Object Name Selection (you can include as many Object Name Selections as required): Field Choose the option you require: Name - the object's short name, for example for a Java function "createStatement" Full Name - the object's full name, for example for a Java function "java.sql.Connection.createStatement" Path - the path to the file storage location of the object. Care should be taken when using the Path criterion for Object Name Selection: in some technologies (such as .NET) objects in one path may hold objects that are present in another path and as a result, you may find that because all children and descendants are included, some objects may be present in multiple paths. As a result an object may be present in multiple modules. As an alternative for the .NET technology, you could: identify namespaces of the items you want and use the Full Name criterion to define the module. use an explicit filter based on a SQL query to define the module. CAST highly recommends consulting the CAST System View "CSV_FILE_OBJECTS" located in the CAST Analysis Service schema to find out how object names and paths have been recorded. Operator Choose the operator you require: EQUALS - use this option to exactly match the Pattern you enter (equivalent to the "=" in SQL) LIKE - use this option in conjunction with the % operator to match similar objects (equivalent to the "LIKE" in SQL): The pattern sales% on Name will return objects such as sales, salesdetails, salesaddresses The pattern %.%..%uth% on Full Name will return objects such as SERVER.CASTPUBS..AuthorIDCodes, SERVER.CASTPUBS..on_delete_authors The pattern %.frm on Path will return all objects whose path ends in .frm MATCH (Perl Regular Expression) > Use this option if you require a more complex pattern based on a Regular Expression. Pattern Enter the string or expression you want to match. Click this button to remove the current Object Filter.

Explicit Filter

This option allows you to define a specific list of objects that will be included in a Module. You can use this tab in conjunction with the Object Filters option - see Combining Object Filters and Explicit Content for more information about how the two filters can function together. The list of objects is determined by the insertion of an SQL query that will be run against the CAST Analysis schema and include any objects that match your query:

The SQL query that needs to be inserted into the editor must use a CAST pre-defined format. The basic format is as follows:

delete from §CI_OBJECTS_SET where set_name = '$(ModuleName)';
 
insert into §CI_OBJECTS_SET(set_name, object_id, error_id)
select '$(ModuleName)', o.object_id, 0
from §CDT_OBJECTS o
where /*fill where clause here*/

This query essentially does the following:

1. Empties the CI_OBJECTS_SET table in the CAST Analysis schema of any existing entries pertaining to the current User Defined Module you are working on (this is determined automatically by the $(ModuleName) macro). § symbol is replaced with application local schema name. 
2. Inserts new data into the CI_OBJECTS_SET table that determines which specific objects must be included, based on:
   • the CDT_OBJECTS table in the CAST Analysis schema (a table that lists all objects that have been saved into the CAST Analysis schema as a result of analyses that have been successfully completed)
   • a where clause that lets you extract specific items from the CDT_OBJECTS table

For example, to specify ALL objects in the CAST Analysis schema that are "SQL Tables", modify the basic format SQL by adding the text in the where clause:

delete from §CI_OBJECTS_SET where set_name = '$(ModuleName)';
 
insert into §CI_OBJECTS_SET(set_name, object_id, error_id)
select '$(ModuleName)', o.object_id, 0
from §CDT_OBJECTS o
where object_type_str = 'SQL Table'

Creating the filter

When the Object Filter configuration is complete, use the Create button in the bottom right corner to create the module:

Click to enlarge

Your new User Defined Module will be listed in the list of modules:

Check a User Defined Module - Check Content

If you have already run an analysis, you can use the Check Content button to check which objects will be matched by the User Defined module and the filters you have defined:

Click to enlarge

Objects matched by the User Defined module and filters will be displayed in two panels to the right:

Click to enlarge

Module per technology

This option will create Modules based on the Technologies that have been "discovered" in your source code. One Module will be created for each Technology that has been delivered in the Version. The modules will be created immediately and then generated at the start of the next analysis/snapshot:

Module per Analysis Unit

This option will create Modules based on the Analysis Units that have been "discovered" in your source code.  One Module will be created for each Analysis Unit that has been discovered in the Version. The modules will be created immediately and then generated at the start of the next analysis/snapshot:

Module per Subfolder

This option allows you to create Modules based on the folders delivered in your source code Version. A configuration screen will be displayed allowing you to select the folder. One module will be created for each Subfolder that is a child of the selected folder. The modules will be created immediately and then generated at the start of the next analysis/snapshot:

Editing an existing User Defined Module

To edit an existing User Defined Module, find it in the list of modules and click the Edit button:

Deleting a User Defined Module

To delete an existing User Defined Module, find it in the list of modules and click the Delete button:

Behaviour of User Defined Modules using Object Filters

Combining Object Filters and Explicit Content

When defining a User Define Module, it is possible to combine various different filter options. A User Defined Module can consist of 0 to N Object Filters (defined in the Filters tab) and 0 to 1 Explicit Filters (defined in the Explicit Filters tab). The result of these options is derived using a UNION between the Object Filter(s) and the Explicit Filter.

Filters

A Filter will target objects using an INTERSECTION of the various filter types. A target object must:

• (if the filter is active) belong to a filtered Technology
• (if the filter is active) AND belong to one of the selected Analysis Units that function using a UNION between Analysis Units
• (if the filter is active) AND match one of the expressions on the Name, Full Name and Path that function using a UNION between expressions
• (if the filter is active) AND group together all conditions on the same field (Object Name, Object Full Name, or Object Path) using the same operator (= or LIKE): these grouped expressions are handled as UNIONS between their respective criteria (OR); then, these three groups are handled as intersections (AND). For example:

Given the following:

Object Name = 'A'
Object Name = 'B'
Object Name LIKE 'C%'
Object Name LIKE 'D%'
Object Full Name = 'X.Y'
Object Full Name = 'X.Z'
Object Full Name LIKE 'Z.T%'
Object Full Name LIKE 'Z.U%'
Object Path = 'a/b'
Object Path = 'c/d'
Object Path LIKE 'x/y%'
Object Path LIKE 'z/t%'

Leads to the following logical criterion:

(Object Name = 'A' OR Object Name = 'B')
AND
(Object Name LIKE 'C%' OR Object Name LIKE 'D%')
AND
(Object Full Name = 'X.Y' OR Object Full Name = 'X.Z')
AND
(Object Full Name LIKE 'Z.T%' OR Object Full Name LIKE 'Z.U%')
AND
(Object Path = 'a/b' OR Object Path = 'c/d')
AND
(Object Path LIKE 'x/y%' OR Object Path LIKE 'z/t%')

Behaviour with regard to child objects

User Defined Modules will always include child objects, i.e:

• children of directly matched objects
• children of children and so on.

This can sometimes be confusing when using user defined modules defined on full paths in CAST dashboards: violations will be displayed for objects that may not necessarily match the the full path defined in the filter. This is because some objects may be child objects. CAST recommends using object filters based on Analysis Units rather than on the full path to avoid having violations returned for child objects that are not specifically part of the filter.

Take the following example. If the filter is based on the full path, for instance SomeCode\NextCode\Comments\src, it will retrieve the file comment1.cs and its children, and children of these children etc. In this situation, we can expect that the Namespace viewComment and objects of the class comment1 to be part of the module. However, since we have matched the namespace viewComment (a child of the comment1.cs file), the class comment2 will also be part of the module as it is a child of the namespace.