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