CMS - Dependencies - using Reference Patterns

Select the options you require by clicking in the check box next to the item.

• J2EE (HTML, JSP, Java, JavaScript VBScript)
• ASP (HTML, ASP, JavaScript, VBScript)
• .NET (ASP, C#, HTML, JavaScript, VBScript, VB.NET)
• Mainframe (CICS, Cobol, IMS, JCL)

The purpose is to enable you to configure specific search parameters for a specific component language if required. When the Reference Pattern is run (see below), the search parameters will be applied to each selected component language independently of the other component languages.

• Don't filter on languages > this option is active by default - the languages filter is disabled.
• Filter on languages (choose below) > choosing this option will enabled to the table below, allowing you to choose the component languages that you want the search to target:
  
  
  Note that if you want to target different component languages with different search parameters (for example one search for HTML and one for JSP), then you must create multiple Reference Patterns and assign them each to specific Dependency Rules.

• Simple (default) > Enter the Regular Expression, word or phrase in the Expression text box that you want the Reference Pattern to target. Please use the Regular Expressions hints and tips to formulate a Regular Expression
• Embedded > Select this option if you want to restrict the search to a specific zone. You can specify the start and end of the zone through Regular Expressions. Then specify the regular expression you want to search for within this zone.

  For example, in a Cobol program, you want to search all code for all instances of PERFORM that can be found between IF and END-IF, and all instances of TEST that can be found between PERFORM and END-PERFORM. Configure the following Embedded Regular Expressions:

  1. Begin = IF Expression = PERFORM End = END-IF
  2. Begin = PERFORM Expression = TEST End = END-PERFORM

  Use the buttons to add, edit or remove Embedded expressions. Using the button will display a popup box enabling you to enter the expressions:

  

  Notes

  • Please note that the limits of the zones you are searching (i.e.: the Begin and End Expressions) MUST NOT be located in comments.
  • Zones can overlap one another and a zone can be included within another zone.
  • Each zone will be searched independently for its own regular expression.

By default this option is left blank, meaning case sensitivity will be ignored.

1. 'select * from TITLES
2. 'select * from _TITLES
3. 'select * from vTITLE
4. 'select * from TITLEAUTHOR
5. 'select * from TITLEAUTHOR, TITLES
6. 'select * from TITLES_AUTHOR
7. 'select * from TITLEA_AUTHOR
8. 'select * from TITLES_____AUTHOR
9. 'select * from TITLESAUTHOR
10. 'select * from TITLE
11. 'select * from TITLEdAUTHOR

...the search string "TITLE[A-Z]+" will identify the following hypothetical results:

• TITLES for examples 1 and 5
• TITLEAUTHOR for examples 4 and 5
• TITLES_AUTHOR for example 6
• TITLEA_AUTHOR for example 7
• TITLES_____AUTHOR for example 8
• TITLESAUTHOR for example 9
• TITLEdAUTHOR for example 11

If you leave this option blank, then the default setting (sub-match) will be applied. In effect this means that the results that are returned will correspond in part to the string you enter in the Expression text box.

The search string "TITLE[A-Z]+" will identify the following hypothetical results:

• TITLES, _TITLES, TITLES for examples 1, 2 and 5
• TITLEAUTHOR for examples 4 and 5
• TITLES_AUTHOR for example 6
• TITLEA_AUTHOR for example 7
• TITLES_____AUTHOR for example 8
• TITLESAUTHOR for example 9
• TITLEdAUTHOR for example 11

Notes

• Please note, however, that if you select Match whole word only and NOT the Match case option, only whole words will be identified. For example, using

  ATTRIBUT[a-z]+

  the following results will NOT be identified:

  A AT ATT ATTRI ATTRIB ATTRIBU ATTRIBUT

  but will go directly to ATTRIBUT instead.

  A Regular Expression will thus match the longest string.

How does it work?

Each time the Regular Expression is matched in the source, the chosen replacement string is produced and is used to match the name (with the same sub/over/whole match options).

Replacement is based on Regular Expression grouping. For example:

• Using the Regular Expression R: ([a-zA-Z_])([a-zA-Z_0-9]+) each parentheses pair generates a grouping and that grouping can be referenced using the notation \1, \2, \etc., \n. If R matches the text "The_Cat" then \1 is the character "T" and \2 is the string "he_Cat".
• Using the Regular Expression S: (HisFunc|MyFunc)\(([^)]*)\). If S matches the text "HisFunc(his_parameter)", then \1 is "HisFunc" and \2 is "his_parameter".

Examples

These examples illustrate how this feature could be used:

1)

• Regular Expression entered: LoadLibrary\("(([^"\r\n]|""|\\")*)\.dll"\)
• Replacement entered: \1
• This combination will match the name of the DLLs (without the extension) called in C/C++ source code

2)

• Regular Expression entered: com\.my_package(\.([a-zA-Z_][a-zA-Z_0-9]*))+
• Replacement entered: \2
• This combination matches the last part of qualified names beginning with com.my_package

3)

• Regular Expression entered: Id(d|x)_Object_([a-zA-Z_][a-zA-Z_0-9]*)
• Replacement entered: Id\1_\2
• This combination matches the the names that have the form "Idd_Object_Something" and then eliminates the "Object" in the middle
• E.g.:
  • Idd_Object_Frame -> Idd_Frame
  • Idd_Object_Window -> Idd_Window
  • Idx_Object_Button -> Idx_Button

4)

• Regular Expression entered: System.loadLibrary\([ \t]*"([^"]+)"[ \t]*\)
• Replacement entered: \1.dll
• This combination matches the names of the C libraries used to call functions via Java native methods

Order of events during execution

A source code analysis has already been carried out and the Analysis Service contains the objects resulting from this analysis. A Reference Pattern is then created and the Enable Replacement option is activated and a replacement text entered in the field. When the Reference Pattern is then run, the following occurs:

• The string chosen as the replacement string is checked for validity, then one of the following occurs:
  • If the chosen replacement string is not valid, the Reference Pattern cannot be executed. The replacement string is considered invalid if it is empty (i.e. nothing entered in the field) or if it contains a reference to a non existent grouping (i.e. \4 whereas the Regular Expression contains only two groups).
  • If the chosen replacement string is valid, the Reference Pattern will then be run. During the process, each time a match with the Regular Expression is located in the selected objects, it is transformed using the chosen replacement string. The result of this transformation is then compared to the names/full names/paths of the Target objects. For each object "A" whose name matches the result of the transformation, a link will be created between the object containing the Regular Expression match and object "A".

Limitations

• The maximum number of groupings that you can reference is 9, which means that if the you specify \10 as a replacement it will be interpreted as \1 followed by the character "0" (zero).

Notes

• It is worth remembering that if the grouping is the object of a repetition then only the last match in the grouping will be retained. Take for example:
  
  - Regular Expression entered: [a-zA-Z_]([a-zA-Z_0-9-])*
  - Match string: James_BrowN - Replacement entered: \1
  
  In this case, \1 corresponds to "N" and not to "ames_BrowN"
  
  Thus there is a difference between the following two Regular Expressions using the same match string and replacement:
  
  - [a-zA-Z_]([a-zA-Z_0-9-])* = "N"
  - [a-zA-Z_]([a-zA-Z_0-9-]*) = "ames_BrowN"

Results are displayed as follows:

The upper section lists the file or files that contain a matched string for the Regular Expression, together with the actual matched string. Clicking on a file will show the file's code and a bookmark (green icon) will be placed on the matched string.

• Object Name > The object's short name
• Object Full Name > The object's full name as stored in the Analysis Service
• Object Path > The path of the object as stored in the Analysis Service

• whole > exact result must correspond to the names of the objects in the Target Selecting this option will force the Reference Pattern engine to look for objects in the Target whose names correspond exactly to the match found in the Source. For example, if the Regular Expression is t_[a-zA-Z0-9_]+ then t_a is a match, so if the Target contains an object named t_a the  a link will be created between the match found in the Source and this object, but there will be no link to an object named zt_a, nor to an object named t_.
  
  You could also use this option to find all references to a database table from the analyzed code. For example, if the table name in the Target is MyTable: use MyTable as the Regular Expression to search for in the Source and select the option Whole. When the Reference Pattern is run you should see links between the following lines int MyTable; // link only if the code option in the Search in section has been checked char * str = "SELECT COUNT(*) FROM MyTable"; // link only if the String Literals option in the Search in section has been checked but there will also be a link to the following line:
  
  char * str2 = "SELECT COUNT(*) FROM MyTable2";
• over > exact result must correspond to part of the names in the Target Selecting this option will force the Reference Pattern engine to look for objects in the Target whose names contain the match found in the Source. For example, if you used the Regular Expression t_[a-zA-Z0-9_]+ then t_a is a match, so if the Target contains an object named t_a, t_atable or t_aMyTable there will be a link between the match found in the Source and these objects.
  
  You could also use this option to find links between the analyzed code and database tables whose names contain a certain word. You could also use this option to find links to a file whose name contains a certain word.
  
  Here's another example: Say you have a file named my_file.cob and you want to find all calls made to it without the extension ".cob". First you enter my_file as the Regular Expression, then you select the option Over, and you ensure that the file "my_file.cob" is in the Target.
• sub > part of the result must correspond to the names of the objects in the Target Selecting this option will force the Reference Pattern engine to look for objects whose names are part of the match found in the Source. For example, if you used the Regular Expression t_[a-zA-Z0-9_]+ then t_a is a match, so if the Target contains an object named t, _a, or t_a there will be a link between the match found in the Source and these objects, but there will be no link to a selected object named zt_a.