| |
|
|
|
8
Debugging objects
This chapter describes techniques for debugging AVS/Express modules and networks.
If you are not debugging the functionality of an individual module, but instead are trying to determine why a network does not work, there are three ways that you can get information about what is happening. You can
- access information about objects in the network
- trace global method execution
- trace operations on specific objects
Most data in AVS/Express is accessible through the Network Editor and/or the VCP. You traverse objects in the Network Editor or the VCP, examining values and connections. In the Network Editor, this is fairly straightforward. You can traverse down to the objects in the network that contain real data values. These values are then displayed on the icon of the object or within the typein that the object displays when you open it.
In the VCP, you need to use V commands to explicitly access information about an object. In the VCP, you can get more information than is displayed in the Network Editor. This table lists some V commands that are useful for debugging networks.
You can determine which methods are executing in what order by turning on the Options->Verbose Functions flag in the Network Editor (this same functionality is enabled with the V command "$set_verbose functions"). When a particular function runs, several pieces of information are printed. Example output for a single method execution is as follows
OM:executing:
func : SingleWindowApp.shell_command.shell_comm_update
arg : SingleWindowApp.shell_command
events : value changed
cause : SingleWindowApp.shell_command.command
- func indicates the pathname of the method that is executing.
- arg indicates the object to which that method belongs.
- events indicates the events that are triggering this object (usually value changed, object instanced or object de-instanced).
- cause indicates the pathname of the object whose event triggered the method to run. In this example, this method ran because the command parameter was changed.
The indentation level of the verbose message indicates the level of nesting of OMpush_ctx/OMpop_ctx routines at the time that this module runs. If the first line of the message is indented by three spaces, it means that this method's execution is being controlled by the explicit use of OMpush_ctx/OMpop_ctx of another running method.
When AVS/Express tries to run an method that has a required parameter that is not valid, it displays a sequence of three messages. The first is a message that indicates that AVS/Express is trying to execute a method. This looks just like the message in the previous example. The second message is an error that is only displayed when the verbose functions flag is enabled:
--- Error detected in: module: OMprim_valid_obj ---
object: Root.Applications.SingleWindowApp.shell_command.command does not have a
value
--------------------------------------------------This message indicates which parameter is not valid. In this case, the invalid parameter is the object shell_command.command. The third message confirms that this module was not run because of the invalid parameter:
OM:is not valid:
func : SingleWindowApp.shell_command.shell_comm_update
arg : SingleWindowApp.shell_command
events : value changed
You can also use the VCP to investigate the validity of objects using the $valid command.
A method fails when it returns a 0 status. After a method has failed, other methods that have a required dependency on the outputs of the method do not run until the method has succeeded again. You can tell from the verbose messages that a message has failed. Immediately after the normal "OM: executing" message, comes the message:
OM:failed:
func : SingleWindowApp.shell_command.shell_comm_update
arg : SingleWindowApp.shell_command
events : value changed
cause : SingleWindowApp.shell_command.command
It is often useful to be able to trace operations that occur on specific objects. For example, if the value of an object is being changed and you do not know which method is responsible, you can trace the set_val operations that occur on that object.
AVS/Express traces the following operations:
By default, AVS/Express traces only set_val operations. You can change
the operations that it traces using the $set_trace and $unset_trace commands.
To begin tracing events on an object, set the trace attribute on that object. You can either use the Properties Editor in the Network Editor or in the VCP. In the VCP you can do this with the statement:
If you are using a source debugger on the process that is performing the operation, you can set a breakpoint in the function OM_stop_here. This function is called each time that a trace message is printed.
If your module is in the main process (usually express), you can simply start the debugger in the normal way for your system using the express process. Once in the debugger, you can set breakpoints normally in the functions defined for your module.
AVS/Express catches the interrupt signal so that it can exit cleanly when you interrupt the program in this way. On some UNIX platforms, this causes the process to exit improperly when you interrupt and continue in the debugger. To work around this problem, you can prevent AVS/Express from catching the interrupt signal by setting the environment variable OM_NO_CRASH_HANDLER before you start the debugger on express.
If you need to debug a process that AVS/Express starts (e.g., the user process), you can use the script xp_dbg. Alternatively, on some operating systems you can "attach" a debugging session to a running process. This requires no extra support in AVS/Express.
The xp_dbg script is located in the bin subdirectory of your installation area. Before AVS/Express has started your process, go to the directory where your executable lives (this usually is the machine specific subdirectory of your local project's bin directory) and type:
At any time, you can set break points in any function you wish to debug. When AVS/Express tries to execute your process, you will see the following message printed in the window where you started xp_dbg:
You have about 20 seconds to type "run" in this window before AVS/Express gives up waiting.
By default, xp_dbg starts up the "standard" debugger used on your operating system. You can change this by using the -debug option and passing the path name of the debugger to use, for example:
The external process starts the first time that an object that needs this process is instanced. The process exits when the last module in the process is deleted.
AVS/Express provides some routines that you can call from the debugger to obtain diagnostic information about the state of your objects while your module is executing.
You can call the routine OMedit_root_obj() to bring up the VCP temporarily while you are in a debugging session. When you call this function, the VCP begins by editing the Root object. You exit the VCP by hitting the EOF character (usually Ctrl-d) to return to your debugging session.
If you have a variable that contains an OMobj_id, you can bring up the VCP directly on that object by calling the OMedit_obj routine. This feature only works if your debugger allows you to pass arguments to the functions. This function takes a single OMobj_id as an argument.
If you want to determine the pathname of an OMobj_id variable that you have, you can call the OMprint_path routine. It takes a single OMobj_id argument and prints the pathname of the object passed to the console window.
Some debuggers do not allow you to passed structures by value as arguments to these routines. In this case, you are not able to call the OMprint_path and OMedit_obj routines directly since they take an OMobj_id as their first and only argument. Instead, you can call the routines OMprint_path_ptr and OMedit_obj_ptr. These routines both take two arguments that correspond to the elem_id and proc_id fields of the OMobj_id. You call them from the debugger like:
If your method does not get called when you change a parameter's value, there are two likely causes.
- This parameter is not properly specified with the notify flag.
- One of the method's parameter is marked as required and does not have a valid value.
To find the problem, you should first turn on the Options->Verbose Functions flag in the Network Editor or with the $set_verbose functions command. This facility prints out a message when AVS/Express attempts to run each method.
If you do not see any messages printed when you change the parameter that should cause your method to execute, it is possible that you do not have notifications set properly on your parameter. Go to the parameter with the VCP and use the $notify command on the object.
For information on how to interpret the output of this command, see Section 3.5.22, $notify [page 3-39]
If AVS/Express is trying to run your method, but finds that your method is not valid, the verbose messages should help you identify the invalid parameter. You can also do this by hand using the VCP. Go to your module object and use the $valid command on the method object. If the method is not valid, then use $valid on each required parameter one at a time until you find the one that is not valid.
For more information on required parameters, see Section 5.3.4, Defining parameter attributes for methods [page 5-7]
If you find that two methods are executing in the incorrect order, make sure that you have defined the methods so that the method that should be running last has a dependency on the method that should be running first.
You can examine the dependencies that a particular method has with the $deps command.
|
| |
|
|
|
Copyright © 2001 Advanced Visual Systems
Inc.
All rights reserved.