GR:Gravity/Xref/TDOMS

From Remain Software
< GR:Gravity‎ | Xref
Revision as of 15:04, 11 September 2020 by Wim (talk | contribs) (Created page with "===Xref for TD/OMS=== Xref for TD/OMS extends the basic Xref search facility to TD/OMS but also adds functionality specific to TD/OMS, for example connecting an Xref hit to a...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Xref for TD/OMS

Xref for TD/OMS extends the basic Xref search facility to TD/OMS but also adds functionality specific to TD/OMS, for example connecting an Xref hit to a task. Below are the Xref related menu options made available by the TD/OMS UI.

Create an Xref location from the TD/OMS Components View

If the Gravity user defined in the Xref preferences is the admin user then the menu option Create Xref location will be made available in the Components view. This option makes it possible to create an Xref location from a component. The availability of the menu also depends on the selected component's source location, if the source location is not set then the menu option will not be shown. For example


Xref create location comp.png


In the above example, the source location DOMSPR1SRC will be extracted from the component and an Xref location will be created with the name 'plato_DEMO_DOMSPR1SRC' (of type lib), where plato is the TD/OMS hostname, DEMO the application name, and DOMSPR1SRC the source library name. The location will be added to the selected or created Xref group. The credentials used by Xref to access the source library are the TD/OMS credentials for the host where the source library resides (in our case the TD/OMS remote system plato). If the credentials do not have sufficient authority to read the source members then a different user name and password need to be provided in the Gravity Xref configuration.


Create an Xref location from the TD/OMS Route Navigator View

If the Gravity user defined in the Xref preferences is the admin user then a menu option Create Xref location will be made available in the Route Navigator view. This option makes it possible to create an Xref location from 1 or more application routes. The selected routes that are to become an Xref location must all be from the same application route. What may only differ per selection set is the environment in which the route is located. For example:


Xref create location navigator 2.png


In the above example, the application route DEPLOY from the environments *ACC and *PRD will be used to set up an Xref location with the name 'plato_DEMO_DEPLOY' (of type tdoms), where plato is the TD/OMS hostname, DEMO the application name and DEPLOY the route name. The location will be added to the selected or created Xref group. The credentials used by Xref to access the IFS files are the TD/OMS credentials for the host where the files reside (in our case the TD/OMS remote system plato). If the credentials do not have sufficient authority to read the IFS files then a different user name and password need to be provided in the Gravity Xref configuration.


Updating a location

If you need to change the setup of an already defined location, for example by adding or removing an environment, then the Xref location has to be removed from the groups it is being used in before an updated location can be created from the Route Navigator.

Menu options on an Xref hit

The Xref find options are made available in the Components, Route Navigator and Impact Analysis view and where the selection will resolve to a valid TD/OMS component. Up to 7 items can be selected for an Xref find. If more than 1 item was selected then a successful find will be based on the fact that all the items have been found in a source. If you want to change the behavior of a multiple selection find then use the advanced find dialog (menu option Find ...) and update the search terms with the +/- sign or the AND/OR operator for example "OMA0042 OR OMA0043 OR OMA0044"

With regards to the Xref result view and IBMi related sources (library or IFS), there are a number of extra menu options that can be made available depending on how the Xref location was created. If a location is created from TD/OMS through the Components view or Route Navigator view then the location will contain extra metadata making it possible to connect Xref hits to a task.

For locations of type lib, ifs or tdoms the option View IBMi source will also be made available. This option will download the current library or IFS source file from the IBMi. This differs from 'View in editor' which downloads the source file from the Xref hosted repository. The editor chosen to open the file will depend on the source file extension. In the RDi, IBMi native source files will be opened in the LPEX editor.

Connect an Xref hit to a task

If an Xref hit (source file) belongs to an Xref location of type lib or tdoms and the location was created from within TD/OMS UI, then a hit can be added to a TD/OMS task. Two menu options will be made available; 'Add to connection list...' and 'Direct connect...'. The menu option will not be enabled if an application task has not yet been selected. With a connect the file to which the hit refers to will be mapped to the current file registered in the TD/OMS database and added to the selected task. In the example below the object of the source file DMD001_2.rpgle can be connected to task T0145 in the application KE110.


Xref connect task2.png

Xref find from within the LPEX editor

Xref can also be accessed from within the LPEX editor (available only in the RDi). You can initiate an Xref search by positioning the cursor on a word or highlighting a number of words, with a right mouse click the menu options 'Find all', 'Find exact' and 'Find ...' will become available for Xref searching.

  • 'Find all' will run a search with the provided text as is, this means that any Xref reserved characters will be interpreted as such, see Advanced Searching section Escaping special characters.
  • 'Find exact' is an enhanced version of the 'Find all' but will attempt to find the text as is, i.e. including special characters used in the text.
  • 'Find...' will start the Xref advanced query wizard, this will allow you to fine-tune the text to be searched and or augment the search with specific Xref attributes (i.e. path, language type ...).


Xref rdi lpex find2.png


In the example above the text PGM(OMX928C) was selected for an Xref search. To just reiterate the difference between the options 'Find all' and 'Find exact' there is a not so subtle difference between the outcome of the two. As explained in 'Advanced Searching' this has to do with the way the text is processed by the Xref search engine. In the chosen example the default 'Find all' will do a search based on 2 words, PGM and OMX928C, this is due to the parenthesis which is an Xref special character used for grouping. With the 'Find exact' the search processing is enhanced to find the exact text 'PGM(OMX928C)' including the parenthesis. A similar situation will arise when running a search on a word containing the special character %, #, $ or @ for example #fldX or %eof(OMERD). A word containing any of these characters will be split up into 2 or more words so you need to use the exact match option to get a sensible collection of hits.