Si2oaD/Interface
From oacwiki
From the command-line of a debugger session or within application code, two sets of interface functions functions are available for accessing data and changing execution options dynamically:
- Overloaded versions of the single function name, oad()
- Uniquely-named functions – For debuggers (like VisualStudio) that have trouble calling overloaded functions at run-time, a non-overloaded equivalent function name is available (colored blue in Table 1).
| Debugger call | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| oad()
oadr() | Display the entire OA state, traversing to each oaObject (the Session, all open Libs, etc), showing all associations. | ||||||||||||||||||
| oad( variable)
oadm( variable) | Display the managed Object represented by the variable named, variable. | ||||||||||||||||||
| oad( variable )
oadu( &variable,"typeName" ) | Display the utility object represented by the variable named, variable. [NOT YET FINISHED] | ||||||||||||||||||
| oad( 0xAddress)
oada( 0xAddress ) | Display the oaObject whose "handle" is Address (which must be preceded by the literal string "0x") . | ||||||||||||||||||
| oad( "com", "arg" )
oado( "com", "arg" ) |
|
Example uses of the various options in the above table can be seen in the testrelease.gold file (2).
Contents |
1 Data Traversal and Display Functions
1.1 Complete RTM
Calling oad() – or the non-overloaded synonym, oadr() – with no arguments wil traverse and display the entire run-time model.
1.2 Managed oaObject
Passing the name of a variable in the code with a valid handle to a managed oaObject to oad() – or the non-overloaded synonym, oadm() – starts the traversal and display with that Object.
The following gdb call to one of the oad() interface functions displays the attributes and relationships of the managed Object, modNet. (The actual line numbers and variable names might be different in the current version or test case being used.)
(gdb) b 111 Breakpoint 2 at 0x8063e39: file testcase.cpp, line 111. (gdb) c Continuing. Breakpoint 2, main (argc=1, argv=0xbfff9f74) at testcase.cpp:123 111 oaBusNet *busNet1 = oaBusNet::create(block, oaScalarName(ns,"busNetA1"),3,20,2); (gdb) call oad(modNet) <oaModScalarNet isPreferredEquivalent='t' id='b75c0613' name='N2' sigType='signal'> <mod ref='#b75c0192' name='Sample'/> <topMod ref='#b75c0192' name='Sample'/> <instTerms> <oaModInstTerm ref='#b75c0693' termName='b'/> </instTerms> <occNets> <oaOccScalarNet ref='#b75c0713' name='N2'/> </occNets> <oaModScalarTerm id='b75c0793' name='T2' isInterface='t' position='UINT_MAX' termType='input'> <mod ref='#b75c0192' name='Sample'/> <topMod ref='#b75c0192' name='Sample'/> <occTerms> <oaOccScalarTerm ref='#b75c0813' name='T2'/> </occTerms> </oaModScalarTerm> </oaModScalarNet>
1.3 Managed Object address
The value of a managed Object variable, i.e., its handle in hex, can be passed as an argument to oad() – or the non-overloaded synonym, oada() – will also produce a traversal and display of that Object. This is useful because handles to other Objects frequently appear in Object associations. Those hex values may not correspond to any active code variables; yet they can still be traversed.
For example, the instTerms relationship in the modNet display above shows a reference to a ModInstTerm handle. The following OAD call uses that Object address directly to display that ModInstTerm:
(gdb) call oad(0xb75c0693) <oaModInstTerm id='b75c0693' numBits='1'> <mod ref='#b75c0192' name='Sample'/> <topMod ref='#b75c0192' name='Sample'/> <net ref='#b75c0613' name='N2'/> <inst ref='#b75c0512' name='Inst1'/> <occInstTerms> <oaOccInstTerm ref='#b75c0913' termName='b'/> </occInstTerms> </oaModInstTerm>
1.4 Utility object
Passing the name of a code variable that represents an OA utility object to oad() will display just that utility object.
This gdb session fragment lists a few lines of code preceding a breakpoint, then calls for OAD display of a few of the utility objects from that code:
(gdb) list 87 82oaParam paramF( "paramF", 2.435 ); 83pa.append( paramI ); 84pa.append( paramF ); 85pa.append( paramI ); 86oaTransform xf( 34, 65, oacMX ); 88oaBusNet *busNet1 = oaBusNet::create( block, oaScalarName(ns,"busNetA1"), 3,20,2 ); 90oaBusTerm *busTerm1 = oaBusTerm::create( busNet1, aScalarName(ns,"busTermA1"), 4,21,2 ); (gdb) call oad(xf) <oaTransform x='34' y='65' orient='MX'/> (gdb) call oad(paramF) <oaParam name='paramF' type='doubleParam' val='2.435000'/> (gdb) call oad(pa) <ParamArray size='3' numElements='7'> <oaParam name='paramInt' type='intParam' val='2435'/> <oaParam name='paramF' type='doubleParam' val='2.435000'/> <oaParam name='paramInt' type='intParam' val='2435'/> </ParamArray>
The non-overloaded oadu() can be used when the debugger cannot pick the right overload. This function has the user provide the address of the variable plus an explicit oaType name. The oadu() interface is useful, for example, with
- the .NET debugger, which generally cannot identify the overloaded symbols in a call
- gdb(), which cannot find an overloaded template symbols (such as Complex and LookupTbl)
The following session fragment illustrates this problem:
(gdb) call oad(complexF) Cannot resolve function oad to any overloaded instance (gdb) call oadu( &complexF, "oaComplex<oaFloat>" ) <?xml version='1.0' encoding='utf-8' ?> <si2oad> <oaComplex oaComplex='(5.6,7.8)'/> </si2oaD>
If the exact name of the oaType cannot be recalled, the debugger can be used to provide that information about the code variable. Note in the following example, the namespace qualifier is reported by gdb but deleted from the Type name for the purpose of calling oad():
(gdb) call oad(vd2DTbl) Cannot resolve function oad to any overloaded instance (gdb) whatis vd2DTbl type = OpenAccess_4::oa2DLookupTbl<int,int,OpenAccess_4::oaViaDefArrayValue*> (gdb) call oadu( &vd2DTbl, "oa2DLookupTbl<int,int,oaViaDefArrayValue*>" ) ...
2 Command Functions
An oad() overload – or the non-overloaded synonym, oado() – can also be passed two string arguments representing a "command" category and the syntax of that command. Such commands produce an action or change the current options state of OAD in some manner.
2.1 Option
Calling oad("o","optionname=value") will set the option with the indicated name to the value following the = character (5).
If the second arg specifies an invalid option name or the empty string, a list of options will be displayed, along with a prompt for a valid name and value
2.2 Read
Calling oad("r","filepath") will read the indicated relative or absolute file path and overwrite the current option settings with those found in that file.
If the empty string, the user will be prompted for the filename. The format of the file must be compatible with that produced by the "write" com; however, only those options to be changed need to be included its contents.
If the second argument is the empty string, a prompt will be made to the command line for its value.
2.3 Write
Calling oad("w","filepath") will write the current options settings to the indicated path.
This will create a usable template in the correct format for option settings files, such as the .si2oadoptions file of initialization settings read automatically by OAD. In situations where several options must be changed, instead of using the "o" command to change them individually, it can be more convenient to
- write an options file with the "w" command,
- edit it in a separate window,
- and then read in the changes with the "r" command.
If the second argument is the empty string, a prompt will be made to the command line for its value.
2.4 Help
Calling oad("h","") will display the current version information along with a terse summary of the OAD interface calls available. The arg is ignored.
2.5 Regex
Calling oad("r","pathExpression") will set up regex matching for the next call to display model data (or all subsequent calls if regexsticky==t). The second arg is a pathExpression (6).
