Introduction

Ensuring the correct discovery of transactions is a multi-step process that may be complex and time consuming for applications that are not supported out-of-the-box. At the core of CAST transaction discovery algorithm is the understanding of the links between objects discovered during the source code analysis of the target application.

CAST automatically sets up default Dependency Rules (see Validate dependency configuration) when the source code is delivered and set as the current version: the source code objects are scanned for references to other objects and links are created where appropriate. Not all links generated in this fashion are valid and their validation by the AIP Super Operator is therefore required.

Missing links result from the inability to find references between objects and can also occur either because of missing dependencies (these may need to be created manually) or because of the presence of frameworks that are not supported out-of the box. In this case, new links may be added by defining new dependencies, custom association rules (using the CAST Reference Pattern tool available in the legacy CAST Management Studio) and/or new, custom environment profiles developed ad hoc to extend the out-of the box support.

For cross-technology links, External Links will identify and record a link between two objects whose validity cannot be precisely determined. These links are tagged as "dynamic". The inspection of these dynamic links is necessary to determine whether the link in question is legitimate (i.e. valid) or if instead it should be ignored and removed from the results.

Why does it matter?

Inspection of dynamic links is a mandatory step. It is a very important step because:

  • it impacts how transactions are discovered and displayed in CAST Imaging
  • it impacts the following diagnostic results specifically for the CAST Engineering Dashboard:
    • Architecture Checker rules (Architecture Model)
    • High Fan-in artifacts (Dependencies)
    • High Fan-out artifacts (Dependencies)
    • Unreferenced components (dead code)
    • Other architecture rules
  • JEE
  • .NET
  • C, C++.
COBOL and Pro*C are less affected, since embedded SQL will produce plain links.

Step 1 - Check Automatic Links Validator extension report

If the Automatic Links Validator extension has been installed for your Application (this is usually true as the extension is automatically set to be "force installed" as part of an extension strategy) then you should first consult the results produced by this extension during the analysis. If the extension is not installed, CAST highly recommends using it. It functions as follows:

  1. The extension checks the dynamic link against a series of heuristics
  2. Each heuristic gives a score (positive or negative) to each dynamic link
  3. All scores are added up to give a final score = θ.
  4. The decision to validate as true, reject as false or skip the links is based on the value of θ:
    • if θ > 0, the link is validated as true
    • if θ < 0, the link is rejected as false
    • if θ = 0, the link is skipped (generally this means that none of the heuristics can be applied to this link and in this case, you will need to review the links manually - see below)

Results are provided in a Microsoft Excel report, which can be accessed as follows:

  • in the Console interface in the Overview page under Reports (note that in Console 2.x this report is available in legacy onboarding mode without fastscan in all releases, and in fastscan onboarding mode from 2.11.x, and for Console 1.x this report is available from 1.25.x):

  • in the LISA folder (Large Intermediate Storage Area) on the appropriate Node, which is usually set to %PROGRAMDATA%\CAST\CAST\CASTMS\LISA:

Step 2 - Manually inspect Dynamic Links

If the Automatic Links Validator extension report indicates a percentage of skipped links, or this extension has not been used for the current Application, you should now proceed with a manual inspection of the links.

Navigate to the Config > Advanced > Summary of Dynamic Links section:

Click to enlarge

View the summary section to see the number of Dynamic Links that need to be reviewed - in the example below, only one link needs to be reviewed - and as shown in the details section, this is a Java Constructor accessing a SQL table:

To review the links, click the Manual Review button:

This button opens a new window where you can manually review each link. By default the window will show all links that need to be reviewed - i.e. all links that are still considered to be "unverified". The first link in the list will be selected and the source code that creates the link will be displayed automatically, along with the specific object highlighted (this is known as a bookmark) - this will help you decide whether the link is correct and needs to be marked as valid, or whether the link is invalid and needs to be marked as ignored:

Click to enlarge

Sometimes, there may be more than one bookmark for a given link. If this is the case, you can move through the bookmarks using the navigation buttons as highlighted below:

Links can, however, be in one of three states, indicated in the Status column:

  • Not reviewed: links displayed in this state when you open the Dynamic Link Manager after the completion of an analysis - these links must be reviewed.
  • Validated: links are in this state when they have already been manually or automatically validated as correct or true. By default Validated links are not displayed in the GUI - you will need to specifically select the Validated check box to display them.
  • Ignored: links are in this state they have already been manually or automatically reviewed as invalid or false. By default Ignored links are not displayed in the GUI - you will need to specifically select the Validated check box to display them.

By default Validated and Ignored links are not displayed in the GUI - you will need to specifically select the Validated / Ignored check box to display them:

Allows you to apply the review status on your links. Note that this button is not active until a specific choice has been made either in the individual settings or in the global settings:

Filters the display of Dynamic Links. By default only To Review is selected, displaying only those links that are unverified and need to be manually reviewed. You can select a combination of any of the options to display the type of links you need.

Note that the Reference Finder filter will display any links that have been created via a Reference Finder rule.

This option is not available if at least one link is selected in the list. Instead radio buttons offering three choices are displayed - this is the action required to review the link:



 Use this button to download the list of Dynamic Links in this section in CSV format.

 Allows you to choose the columns that are displayed in the table. By default all are displayed:

Provides options for further filtering the display of links. The filtering is based on simple text strings - therefore entering "com" in the Source Object field and applying the filter will only display objects whose name contains the word "com":

Click to enlarge

  • Use the Reset button to remove all filters
  • Use the Apply Filters button to apply the filters you have added.

The tick boxes enable you to perform review actions on single or multiple links at a time. You can also use the SHIFT key combined with mouse clicks to select multiple links.


Source ObjectLists the name of the object that contains the code for the "source" of the link.
Source TypeLists the type of source object - i.e. Method, Constructor, table etc.
Target ObjectLists the name of the object that is the target of the link in the source object.
Target TypeLists the type of source object - i.e. Method, Constructor, table etc.
LinkLists the type of link between the two objects.
Status

Current status:

  • Validated: links are in this state when they have already been manually or automatically validated as correct or true. By default Validated links are not displayed in the GUI - you will need to specifically select the Validated check box to display them.
  • Ignored: links are in this state they have already been manually or automatically reviewed as invalid or false. By default Ignored links are not displayed in the GUI - you will need to specifically select the Validated check box to display them.
  • Not reviewed: links displayed in this state when you open the Dynamic Link Manager after the completion of an analysis - these links must be reviewed.

Validate/Ignore/To Do radio buttons

These radio buttons allow you to choose what to do with the link after reviewing its code. Select the appropriate option for the link and then click Apply in the top right corner to confirm the choice. You can use the check boxes to review multiple links:

Click to enlarge

The process of reviewing Dynamic Links is as follows. Ensure that the filter is set to To Review:

Tick the link you want to review:

If there are multiple dynamic links that you want to Validate (as correct) or Ignore (as false) in one go, you can select multiple using the mouse or using the SHIFT key+mouse combination:

If necessary, check the source code to help you decided if the link is correct and needs to be marked as valid, or whether the link is invalid and needs to be marked as ignored:

Click to enlarge

Click the appropriate radio button to either Validate (as correct) or Ignore (as false) the link)

Ignore Dynamic Links when:

  • Source code uses a logger information message
  • Basic text displayed in a message box or a frame

Validate Dynamic Links when:

  • code uses a manipulation of SQL queries

  • code uses a direct call from a business layer to a database table or function

  • code links a client part and a server part of an application

Finally click the Apply button to confirm the change in status of the link, then close the window:

The Summary/Details screen will then update to reflect your changes.

Click here to expand...

You can use CAST Enlighten on the relevant AIP Node and connect to the Analysis schema associated to the Application in question. Use the Administration Center - Applications - Application Details to find out the name of the Analysis schema you will need to connect to in CAST Enlighten:

Click to enlarge

Once connected to CAST Enlighten, you should use the Dynamic Link Manager (DLM) which is accessible from the Tools > Dynamic Link Manager menu:

Links can be in three states within the Dynamic Link Manager:

  • To be reviewed: links are in this state when you open the Dynamic Link Manager after the completion of an analysis.
  • Ignored: links are in this state when you have ticked them after examination (and they prove to be invalid/false). By default Ignored links are not displayed in the GUI - toggle the Hide Reviewed Links button to view them.
  • Validated: links are in this state when you have marked them as Validated after examination (and they prove to be valid). By default Validated links are not displayed in the GUI - toggle the Hide Reviewed Links button to view them.

Invalid links must be "ignored/rejected" after reviewing the code that creates the link (by ticking the box next to link):

  • Ignore/reject Dynamic Links when:
    • Source code uses a logger information message
    • Basic text displayed in a message box or a frame

These actions will remain valid for the next re-analysis. 

Valid links must be "validated" after reviewing the code that creates the link (by right clicking the link and selecting Validate)

  • Validate Dynamic Links when:
    • code uses a manipulation of SQL queries

    • code uses a direct call from a business layer to a database table or function

    • code links a client part and a server part of an application

These actions will remain valid for the next re-analysis. 

  • when in doubt, ignore Dynamic Links not resolved automatically through an extension, parameterization / filter rules or via manual selection.
  • all Dynamic Links are by default assumed as if they were validated and are saved as part of the results.
  • you can close the Dynamic Link Manager in the middle of a review session and changes will persist.

In AIP Console, perform an Application resync to ensure that AIP Console is fully up-to-date with the changes made in CAST Management Studio:

Notes

Manually reviewing Dynamic Links (although a legitimate approach) is discouraged as it will not address the underlying cases that triggered the detection in the first place and it can be very time consuming, particularly if you have a large number of dynamic links to review. CAST therefore recommends the use of other options to automate this process as described below. If any of these options are used, they will require an additional analysis so that they are triggered.

Note that any custom Dynamic Link rule files can be packaged as a custom CAST AIP extension for sharing in the wider CAST user community.

Dynamic Link Manager rule files enable you to create XML based filter rules that can be applied in the AIP Console at global (all Applications) or Application level: each time an analysis is then run, the filter rules will be applied, either validating or ignoring links as required.

Click here to expand...

Take the following example rule file and the filters defined in it:

<?xml version="1.0" encoding="utf-8"?>
<dynamicLinksRules xmlns="http://www.castsoftware.com/DlmRulesModel.xsd" >
<rule name="Rule1" action="validate" >
<scope>
<application name="app1"/>
<application name="app2">
<analysisUnit name="au21"/>
</application>
<application name="app2">
<technology name="J2EE"/>
</application>
</scope>
<calleeName regexp="a2"/>
<calleeType names="A_Metamodel_Type"/>
<callerFullName regexp="a4"/>
</rule>

<rule name="Rule2" action="ignore">
<calleeFullName regexp="a4"/>
</rule>
</dynamicLinksRules>

When this rule is used:

  • Rule1 will be processed first (this has a validate action)
  • The entire set of unreviewed Dynamic Links that are available in the Analysis Service will be taken into account

  • The following actions are then executed in the following order:

    • Selecting as a scope all links that belong to:

      • Application app1

      • The Analysis Unit au21 located in Application app2

      • All J2EE links in the application app2

    • Filtering by callee name = a2
    • Filtering by callee type = A_Metamodel_Type
    • Filtering by caller full name = a4
    • Tag the result as Validate
  • Then Rule2 will be processed
  • The entire set of unreviewed Dynamic Links that are available in the Analysis Service will be taken into account (there is no scope specified at all), except the links that have been processed by Rule1.
  • The following actions are then executed in the following order:
    • Filtering by callee full name= a4
    • Tag the result as Ignore

To associate your rule file in the AIP Console, do as follows.

Application level

To apply the filter rule at Application level, use the Config > Application - Config - Update Application schema option in the Application. See Application - Config - Update Application schema for more details about how to create the rules files.

Global (all Applications) level

To apply the filter rule at Global (all Applications) level requires a user with the Admin role and is actioned in the Administration Center. See Administration Center - Settings - Default Dynamic Links Rules for more information about this option:

You can leverage method Parametrization to automatically ignore or validate links when they are created with a parameter of a method. Parameterization rules allow you to automatically exclude Dynamics Links when you re-run the analysis. Moreover, Parametrization rules can be reused in future analyses (via an Environment Profile) thus supporting the automation of the analysis process. CAST provides some default parametrization rules and you can also create your own.

Methods are defined in custom environment profiles, and these custom profiles can be selected in the Dynamic Link Manager in the CAST Management Studio.

A C++ link may possibly have several different associated pieces of code (in various files). When a server object is referenced in several files for a same Caller, CAST's Dynamic Link Manager will only display references found in one file.

For example:

<pre>file f1.h :
....
void f(const CString&amp; s = CString(&quot; T1&quot; ) );
...
file f2.cpp
...
void f( const CString&amp; s )
{
//...
LPSTR c = &quot;T1&quot;;
//...
}
...</pre>

In this example, T1 is a server object and function f references T1. The references are spread among two files, f1.h and f2.cpp.

Although there is more than one file that contains references to T1, the Dynamic Link Manager will only display one file (either f1.h or f2.cpp) and highlight all references in it. Thus all references in the other file will not be displayed. In this example, if the file displayed by Dynamic Link Manager is f2.cpp, there will be only one reference highlighted although there is another reference in f1.h. Therefore it can be difficult to decide if links to T1 are valid or should be ignored.

To workaround this problem, you can use the Code Viewer in CAST Enlighten. It displays all bookmarks. This allows dynamic links to be evaluated based on complete information.

Dynamic links will be created to macros based on the source code that is defined in a macro. However, when examining these dynamic links in the Dynamic Link Manager, the link will appear to originate in the macro and call any corresponding object based only on the strings that are defined in the macro. This is a functional limitation of the analyzer. In order to check the validity of these links, the corresponding file where the macro is defined will need to be opened manually.