Search¶
Introduction¶
The Search screen allows answering questions about an entire project (or a subset of a project if a Profile is used). Any question that can be formulated as a single boolean expression can be answered using this tool.
More importantly, these expressions have full visibility to the 4GL language syntax itself. This happens naturally because the expressions are directly referencing the structure and contents of the AST itself. The AST is the purest form of the 4GL language syntax.
Traditional text based searches and even tools like grep (regular expression searching) have no built-in awareness of the 4GL syntax.
The approach:
- Write expressions of arbitrary complexity that match based on the full richness of the AST.
- The TRPL engine does the tree walk, the expression just specifies exactly what is wanted in a match.
- The TRPL expression syntax has many features that make it easier to process AST concepts, including the knowledge of the current AST node being visited.
- Code that cannot be implemented in a single expression can be put into a callable TRPL function and accessed from expressions. This enables techniques like storage of temporary state (during the lifetime of the function call) as well as the creation of tools that can be used for many purposes.
- All AST nodes and other data being accessed are actually Java objects. You can call Java instance methods (no statics or generics at this time) on these objects and you can pass those same objects to Java methods or to TRPL functions.
- TRPL has a wide range of advanced AST processing features that can be leveraged.
This chapter does not discuss how to write expressions. See Writing TRPL Expressions for details in that regard. This chapter simply explains how to use the Search screen.
Usage¶
The screen is deceptively simple for the power it holds. This is the screen on initial entry:
There are 3 "controls" here:
- A check-box to control if the active file filter should be honored.
- The radio button to toggle between Code AST and Schema AST for searching.
- The text entry field in which the match condition is written.
By default, searches will honor whichever profile is marked Active in the File List Filters screen. Uncheck this box if the active profile should be ignored. This would result in all files being searched.
Searches are done on either Code ASTs or on Schema ASTs, but not both at the same time. By default, Code ASTs are searched. Use this control to switch between the AST types for the search run:
There is a text entry field for typing the TRPL expression that specifies the search condition:
The user can type directly into this field. As an alternative, pressing the arrow down button on the right will show the entry field's drop down list. This list shows any previous expressions that ran successfully. This is shared between all users and will be persisted across report server restarts. These even are automatically exported into an XML file at report server shutdown and re-imported whenever the reports are re-generated. This ensures that the search expressions are available permanently.
The following is an example of how to search for all references to the hotel.guest.last-name field:
See Writing TRPL Expressions for details on how to write an valid TRPL expression.
After typing this expression, press the Run button to execute the search. The report server will dynamically search the Code ASTs or the Schema ASTs for matches to this expression. All matches will be listed in the results at the bottom of the screen, as shown here:
These results are similar to a Details Report. Each row is a single location in the project that matched the given search condition. Just as can be done in the Detail Reports, it is possible to click on a row:
This will load the Source View for the AST node associated with the search match:
The search condition can be edited and enhanced in an iterative manner. Pressing Run will execute the search using the latest condition expression and will load the results into the screen:
If the expression is invalid (does not parse or pass validation) or if it results in a runtime error, the user will be notified:
Dismiss the error notification and edit the expression to resolve the error.
Errors¶
It should be noted that at this time, the error reporting is a bit "raw", as the error message displayed in the notification is taken directly from the TRPL engine when it parses, compiles, or applies a search expression. These messages originally were designed for TRPL programmers and are not necessarily user friendly. This is a known issue (#3337-2) which will be addressed as resources permit.
That being said, the most common error usually is a reference to a token type that does not exist (such as some_broken_stuff in the example above). Often, people will forget to specify a token type name with the prog qualifier, which is needed to identify a Progress AST token type in a search expression. For example,
type == kw_find /* incorrect */
instead of
type == prog.kw_find /* correct */
Another variation of this mistake is simply to get the name of a token type wrong, for example,
type == prog.find /* incorrect */
instead of
type == prog.kw_find /* correct */
Since there are so many different token types in the Progress language syntax, it is best to refer to a definitive reference to make sure you are specifying the token type intended. In this case, that reference is the FWD source code; specifically,
com/goldencode/p2j/uast/progress.g or com/goldencode/p2j/uast/ProgressParserTokenTypes.txt (note that the latter is only generated once the FWD project is built from source).
Another very common search expression pitfall for those accustomed to ABL programming is that TRPL uses the == operator to test equivalence and the = operator for an assignment operation. ABL uses the = operator for both equivalence and assignment, depending upon context. Assignment is not meaningful in a search expression, so one will always want to use == to test the equivalence of two operands. However, it is easy to mistype this operator as = out of habit. This error will result in a rather cryptic error message from the TRPL engine like, java.lang.Integer cannot be cast to java.lang.Long. If you see something like this, be sure to check your comparison operators.
For additional context on a particular error, it may be helpful to look at the report server log file, normally located at ./deploy/server/report_server.log (relative to the project home directory), which contains more verbose error logging than is reported by the web application.
If it is still not clear what caused a search expression error, please look for a similar issue in the FWD Conversion Forum (https://proj.goldencode.com/projects/p2j/boards/2) or post a new question there.
Finally, please note that the message, No matches found for the given criteria is not an error. It indicates that your search expression was valid, but the condition it represented simply did not match any of the ASTs searched.
© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.
