Core AVS/Express and the Object Manager


Debugging objects

This chapter describes techniques for debugging AVS/Express modules and networks.

This chapter discusses:

8.1 Debugging 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

8.1.1 Accessing object information

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.

V command
Displays an object's...
integer value
real value
string value
pointer value
array value (useful for small arrays)
array value (useful for large arrays)
list of connections to other objects
list of connections from other objects
array size
array dimensions
full pathname in the object hierarchy
value (the end of a chain of connections)
sequence number
current V description

For more information on a particular command see Section 3.5, V commands  [page 3-24]

8.1.2 Tracing method execution

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

func : SingleWindowApp.shell_command.shell_comm_update
arg : SingleWindowApp.shell_command
events : value changed
cause : SingleWindowApp.shell_command.command

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. Message for invalid methods

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

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.

See Section 8.2.4, Determining why a method will not execute  [page 8-9] Message for methods that return 0 status

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:

func : SingleWindowApp.shell_command.shell_comm_update
arg : SingleWindowApp.shell_command
events : value changed
cause : SingleWindowApp.shell_command.command

8.1.3 Tracing operations on specific objects

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:

This operation occurs when the object's...
value is changed
value is accessed
reference count is decremented
subobject list is modified
notification list is modified
is executed (for method objects only)

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.

See Section 3.5.40, $set_trace and $unset_trace  [page 3-53]

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.

8.2 Debugging modules

8.2.1 Using a source debugger on the main process

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.

8.2.2 Using a source debugger on an external process

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:

xp_dbg executable_name

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:

executable_name instance waiting, fire when ready...

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:

xp_dbg -debug sdb executable_name

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.

8.2.3 Getting object information while debugging your module

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. Invoking the VCP from the debugger

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.

See Section 1.32, OMedit_obj  [page 1-64] Printing an object's path from the debugger

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.

See Section 1.84, OMprint_path  [page 1-161] Problems passing OMobj_ids as arguments

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:

OMprint_path_ptr(obj_id.elem_id, obj_id.proc_id)

8.2.4 Determining why a method will not execute

If your method does not get called when you change a parameter's value, there are two likely causes.

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.

See Section 8.1.2, Tracing method execution  [page 8-3]

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]

8.2.5 Finding problems with execution order

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.

See Section 5.3.7, Controlling method execution order  [page 5-14]

You can examine the dependencies that a particular method has with the $deps command.

See Section 3.5.7, $deps  [page 3-31]