tvscript External Script Files

The section tvscript Command Syntax discussed the command-line options used when invoking the tvscript command. You can also place commands in a file and provide them to tvscript using the -script_file command-line option. Using a script file supports the use of Tcl to create more complex actions when events occur. The following sections describe the functions that you can use within a CLI file.

Logging Functions API

tvscript_log msg

Logs a message to the log file set up by tvscript.

tvscript_slog msg

Logs a message to the summary log file set up by tvscript.

Process Functions API

tvscript_get_process_property process_id property

Gets the value of a property about the process.

The properties you can name are the same as those used with the TV::process command. See “process” for more information.

Thread Functions API

tvscript_get_thread_property thread_id property

Gets the value of a property about the thread.

The properties you can name are the same as those used with the TV::thread command. See “thread” for more information.

Action Point API

tvscript_add_actionpoint_handler actionpoint_id actionpoint_handler

Registers a procedure handler to call when the action point associated with actionpoint_id is hit. This actionpoint_id is the value returned from the tvscript_create_actionpoint routine. The value of actionpoint_handler is the string naming the procedure.

When tvscript calls an action point handler procedure, it passes one argument. This argument contains a list that you must convert into an array. The array indices are as follows:

event—The event that occurred, which is the action point

process_id—The ID of the process that hit the action point

thread_id—The ID of the thread that hit the action point

actionpoint_id—The ID of the action point that was hit

actionpoint_source_loc_expr—The initial source location expression used to create the action point

tvscript_create_actionpoint source_loc_expr

Creates an action point using a source location expression.

This procedure returns an action point ID that you can use in a tvscript_add_actionpoint_handler procedure.

source_loc_expr

Sets a breakpoint at the line specified by source_loc_expr or an absolute address. For example:

[[##image#]filename#]line_number

Indicates all addresses at this line number.

A function signature; this can be a partial signature.

Indicates all addresses that are the addresses of functions matching signature. If parts of a function signature are missing, this expression can match more than one signature. For example, “f” matches “f(void)” and “A::f(int)“. You cannot specify a return type in a signature.

You can also enter a source location expression with sets of addresses using the class and virtual keywords. For example:

class class_name

Names a set containing the addresses of all member functions of class class_name.

virtual class::signature

Names the set of addresses of all virtual member functions that match signature, and that are in the classes or derived from the class.

If the expression evaluates to a function that has multiple overloaded implementations, TotalView sets a barrier on each of the overloaded functions.

Event API

tvscript_add_event_handler event event_handler

Registers a procedure handler to call when the named event occurs. The event is either error or actionpoint.

When tvscript calls an event handler procedure, it passes one argument to it. This argument contains a list that you must convert into an array.

error

When any error occurs, the array has the following indices:

event—The event, which is set to error

process_id— The ID of the process that hit the action point

thread_id—The ID of the thread that hit the action point

error_message—A message describing the error that occurred

actionpoint

When any action point is hit, the array has the following indices:

event—The event, which is set to actionpoint

process_id—The ID of the process that hit the action point

thread_id—The ID of the thread that hit the action point

actionpoint_id—The ID of the action point that was hit

actionpoint_source_loc_expr—The initial source location expression used to create the action point