(Engine-Level Function)
| Description: | Returns a linked list of structures representing all references to a specified variable or module. |
| Returns: | Linked list of structures |
Usage:  |
Script Only. |
| Function Groups: | Advanced Module |
| Related to: | |
| Format: |
CrossReference(ModuleToSearch [, WhatToFind, Context]) |
| Parameters: |
| ModuleToSearch |
| Required. Module value which is the root of the static module tree to search. May also be an array of module values. If the next parameter (ModuleToFind) is invalid, then only the variable references which are not within the scope of this module are returned, i.e. external references. |
| WhatToFind |
| Optional. May be either a module or a variable to search for. If invalid, all references to all variables (whether they may contain modules or otherwise) outside the specified scope tree are returned. |
| Context |
| Optional. Instance of a module that indicates what scope ModuleToSearch would run in, were it to run. (Note that ModuleToSearch does not need to be running when CrossReference is called.) If invalid, only the static scope will be searched. |
| Comments: | Context must be valid where scoping needs to be resolved as shown in the example. In this example, it is necessary to determine if the Draw module referred to is the correct one based up on the module value of the actual Draw variable stored in Tag23’s module. |
Example:
Assume that there is page named MyPage whose only line is the following:
Variable("Tag23")\Draw(Variable("Flow")\Value * 10, 57);
Further, assume that Tag23 is of type MyTagType
Then, to look for all references to MyTagType's Draw method inside a particular page, use:
CrossRefData = CrossReference(\MyPage, \ MyTagType \Draw, Code);
You could then expect the following to be true.
CrossRefData.Reference == FindVariable("Draw", \MyTagType, 0, 0)
CrossRefData.DAG == the code value for the Call to the Draw method
CrossRefData.Begin == the number of bytes from the beginning of the
Function to the beginning of the text "Draw".
CrossRefData.End == the number of bytes from the beginning of the
Function to the end of the text "Draw".
CrossRefData.Next = Invalid, assuming there are no other references
to MyTagType’s Draw method on the page.
If you wanted to find all the external references in a section of code (i.e. all references to values that aren’t actually declared in the MyPage module), then you could use the function like so:
CrossRefData = CrossReference(\MyPage, Invalid, Code);
You would expect the linked list in CrossRefData to have nodes for each of the following: Tag23, Draw, Flow, and Value since they are all variables that were not declared in MyPage.
If, for example, the CrossReference code was not able to find a variable called Flow in Code, then the Reference value for that node in the CrossRefData would be the text "Flow" rather than a variable value for Flow. This is because there simply wasn’t a variable named Flow declared in the app. The node for Value would also have the text "Value" instead of a variable value, because if it cannot find the variable for Flow, it follows that it won't find Flow\Value.
The linked list of structures, as returned by this function, are ordered such that the Begin fields are in strictly descending order for each unique file. This is because, if the list is processed in the order returned then multiple search and replace processes done within the same file will not interfere with each other .
All structures for a given file are consecutive in the linked list. In other words, the last reference in the source file will be the first one on the list.
The following tasks can be facilitated without the need to run the code being examined:
- Changing the name of a variable or module
- Moving a variable/module to a different scope
- Removing references to a deleted variable/module
- Giving a cross-reference to locations where a variable/module is referenced
- Re-ordering the parameters to a module
- Locating all variable/module references in a higher scope
