RAPID symbol search
Overview
Most RAPID elements (variables, modules, tasks, records and so on) are members of a symbol table, in which their names are stored as part of a program tree structure.
It is possible to search this table and get a collection of RapidSymbol objects, each one including the RAPID object name,
location, and type.
Search method
The search must be configured carefully, due to the large amount of RAPID symbols in a system.
To define a query you need to consider from where in the program tree the search should be performed,
which symbols are of interest, and what information you need for the symbols of interest.
To enable search from different levels, the SearchRapidSymbol method is a member of several different SDK classes,
for example Task, Module and Routine.
The following example shows a search performed with Task as the starting point:
RapidSymbol[] rsCol;
rsCol = aTask.SearchRapidSymbol(sProp, "num", string.Empty);
The SearchRapidSymbol method has three arguments. The first argument, of data type RapidSymbolSearchProperties, is detailed in
the next section. The second and third arguments are detailed in the following sections.
Search properties
The RapidSymbolSearchProperties type is complex and requires some knowledge about RAPID concepts.
It is used to specify search method, type of RAPID symbol to search for, whether the search should be recursive, whether the symbols are local and/or global, and whether or not the search result should include only symbols currently used by a program. If a property is not valid for a particular symbol, it will be discarded and will not exclude the symbol from the search result.
The table describes the different properties of RapidSymbolSearchProperties.
| Property | Description |
|---|---|
| SearchMethod | Specifies the direction of the search, which can be Block (down) or Scope (up). Example: If the starting point of the search is a routine, a block-search will return the symbols declared within the routine, whereas a scope-search will return the symbols accessible from the routine. |
| Types | Specifies which RAPID type(s) you want to search for. The symbolTypes enumeration includes Constant, Variable, Persistent, Function, Procedure, Trap, Module, Task, Routine, RapidData and so on. (Routine includes Function, Procedure and Trap. RapidData includes Constant, Variable and Persistent.) |
| Recursive | For both block and scope search it is possible to choose if the search should stop at the next scope or block level or recursively continue until the root (or leaf) of the symbol table tree is reached. |
| GlobalSymbols | Specifies whether global symbols should be included. |
| LocalSymbols | Specifies whether local symbols should be included. |
| InUse | Specifies whether only symbols in use by the loaded RAPID program should be searched. |
Default instance
RapidSymbolSearchProperties has several static methods that return a default instance.
RapidSymbolSearchProperties sProp = RapidSymbolSearchProperties.CreateDefault();
The default instance has the following values:
| Property | Value |
|---|---|
| SearchMethod | SymbolSearchMethod.Block |
| Types | SymbolTypes.NoSymbol |
| Recursive | True |
| GlobalSymbols | True |
| LocalSymbols | True |
| InUse | True |
Using this instance you can specify the search properties of the search you want to perform.
Example:
sProp.SearchMethod = SymbolSearchMethod.Scope;
sProp.Types = SymbolTypes.Constant | SymbolTypes.Persistent
sProp.Recursive = false;
Note
The default instance has the property Types set to NoSymbol. It must be specified in order for a meaningful search to
be performed.
The Types property allows you to combine several types in a search. See the preceding example.
See API Reference for the static methods CreateDefaultForData and CreateDefaultForRoutine.
Data type argument
The second argument of the SearchRapidSymbol method is the RAPID data type written as a string. The data type should be written
with small letters, for example “num”, “string” or “robtarget”. It can also be specified as string.Empty.
Note
To search for a UserDefined data type, the complete path to the module that holds the RECORD definition must be passed.
For example:
result = tRob1.SearchRapidSymbol(sProp, "RAPID/T_ROB1/MyModule/MyDataType",
string.Empty);
However, if MyModule is configured as -Shared the system sees its data types as installed, and the task or module should
be included in the path.
result = tRob1.SearchRapidSymbol(sProp, "MyDataType", string.Empty);
Symbol name argument
The third argument is the name of the RAPID symbol. It can be specified as string.Empty if the name of the symbol to retrieve
is not known, or if the purpose is to search ALL “num” data in the system.
Instead of the name of the RAPID symbol a regular expression can be used. The search mechanism will then match the pattern of the regular expression with the symbols in the symbol table. The regular expression string is not case sensitive.
A regular expression is a powerful mechanism. It may consist of ordinary characters and meta characters. A meta character is an operator used to represent one or several ordinary characters, and the purpose is to extend the search.
Within a regular expression, all alphanumeric characters match themselves, that is, the pattern “abc” will only match a symbol named “abc”. To match all symbol names containing the character sequence “abc”, it is necessary to add some meta characters. The regular expression for this is “.*abc.*”.
The available meta character set is shown below:
| Expression | Meaning | |
|---|---|---|
| . | Any single character | |
| ^ | Any symbol starting with | |
| [s] | Any single character in the non-empty set s, where s is a sequence of characters. Ranges may be specified as c-c. | |
| [^s] | Any single character not in the set s. | |
| r* | Zero or more occurrences of the regular expression r. | |
| r+ | One or more occurrences of the regular expression r. | |
| r? | Zero or one occurrence of the regular expression r. | |
| (r) | The regular expression r. Used for separate that regular expression from another. | |
| r | r’ | The regular expressions r or r’. |
| .* | Any character sequence (zero, one or several characters). |
Example 1
"^c.*"
Returns all symbols starting with c or C.
Example 2
"^reg[1-3]"
Returns reg1, Reg1, REG1, reg2, Reg2, REG2, reg3, Reg3 and REG3.
Example 3
"^c.*|^reg[1,2]"
Returns all symbols starting with c or C as well as reg1, Reg1, REG1, reg2, Reg2 and REG2.
SearchRapidSymbol example
This example searches for VAR, PERS or CONST num data in a task and its modules. The search is limited to globally declared symbols.
By default the search method is Block, so it does not have to be set.
RapidSymbolSearchProperties sProp = RapidSymbolSearchProperties.CreateDefault();
sProp.Types = SymbolTypes.Data;
sProp.LocalSymbols = false;
RapidSymbol[] rsCol;
rsCol = aTask.SearchRapidSymbol(sProp, "num", string.Empty);
Search for UserDefined RAPID data - example
In this example a user defined RECORD data type (“mydata”) is declared in a module (“myModule”). Assuming that the end-user can declare and use data of this data type in any program module, the search method must be Block (default). A search for all “mydata” instances may look like this:
RapidSymbolSearchProperties sProp = RapidSymbolSearchProperties.CreateDefault();
sProp.Types = SymbolTypes.Data;
RapidSymbol[] rsCol;
rsCol = aTask.SearchRapidSymbol(sProp, "RAPID/T_ROB1/MyModule/mydata", string.Empty);
rsCol = aTask.SearchRapidSymbol(sProp, "mydata", string.Empty);
Note
If myModule is configured as -Shared and all mydata instances are declared in the search method must be set to Scope and
the SearchRapidSymbol call should look like this:
rsCol = aTask.SearchRapidSymbol(sProp, "mydata", string.Empty);