ZAP

 

 

NAME
	zap - The command-line Java(tm) bug zapper.
	Copyright (c) 1996, Software Farm, Inc.
	"Java" is a registered trademark of Sun Microsystems.
SYNOPSIS
	zap [-applet] [-password <password>] [-host <hostname>] 
		[java options] [class-to-debug] [class-to-debug-arguments]
AVAILABILITY
	Zap is distributed as shareware and includes both the source and 
	class files. If you are still happy with Zap after the thirty 
	(30) day free trial period please send $25 to:
		Software Farm, Inc.
		211 HighView Drive
		Boulder CO  80304
	to help defray development costs. Registered users will be promptly 
	notified of updates when they become available.
DESCRIPTION
	zap is a program written in Java that is used to examine and debug
	programs written in Java, including both applications and applets.
	It uses the command-line standard terminal (TTY) interface for both 
	input and output.
	The [class-to-debug] is a Java application class file that either 
	includes a main() function as the entry point or an applet, in which
	case the [-applet] option must be used. 
	If no [class-to-debug] is specified then it can be specified in
	exactly the same way from the zap debugger command-line using the 
	'debug' command.
	zap is also able to debug remote Java sessions. The remote host is
	specified using the [-host <hostname>] and [-password <password>]
	options. The password is obtained from the remote Java interpreter
	upon startup by using the java '-debug' option. for example:
	C:\> java -debug myRemoteApplet
	The password is ACZD5...
	In order for the zap debugger to examine local variables within a
	class file method the class must be compiled (using javac) with the 
	'-g' option.
OPTIONS
	-applet	
		
		Specifies that the debugged program is an applet.
	-password <password>
		Specifies that the zap debugger is to attach to a Java 
		interpreter that is already running. This other interpreter
		had been started with the -debug option which caused it to
		print out the given password.
	-host <hostname>
		Specifies that the zap debugger is to debug a program already
		running on another machine on the network and the machine is
		called <hostname>. This option is used in conjunction with
		the -password option.
	java options
		These options are passed straight through to the Java 
		interpreter when it is started. Any valid Java interpreter
		option is valid (for example -classpath).
	class-to-debug
		This is the name of the class to debug. It must be the full
		name including any package identifiers and excluding the
		.class extension.
	class-to-debug-arguments
		These are the arguments, if any, to the debugged program.
USAGE
	The basic command set consists of 'run', to run the debugged program,
	'print', to display the value of a variable or contents of a object,
	'where', to display the call stack and 'stop', to set a breakpoint.
	GENERAL COMMANDS
	help [command]
		Display the general help message or help for the specified 
		command.
	
	run [args]
		Run (begin executing) or re-run the current program being 
		debugged. The specified arguments are passed to the program. 
		If no arguments are specified here then the arguments specified 
		in the last run are used. If this is the first run then the 
		arguments (if any) specified on the Zap command-line are used.
		The current program is specified either on the Zap command-line 
		or by using the 'debug' command. Note that this differs from 
		'jdb' (but resembles 'dbx') in that the current program cannot 
		be specified as an argument to the 'run' command.
	debug [program [args]]
		Display or specify the program to debug and it's arguments. Zap
		command-line arguments may be specified at this time.
		Examples:
			> debug -applet ../demo/example1.html
			> debug jeo.Demo -f
	quit | exit
		Quit running the debugged program and exit the debugger.
	kill
		Quit running the debugged program and reinitialize the debugger.
	zapenv
		Display Zap's properties. This will display the properties 
		of the debugger such as classpath, os version, etc. At this 
		time there is no way to access the properties of the debugged 
		program.
		Example:
			> zapenv
			java.home        = /home2/docs/java/jdk/java/bin/..
			java.version     = 1.0
			file.separator   = /
			line.separator   = 
 
			java.vendor      = Sun Microsystems Inc.
			user.name        = michael
			os.arch          = sparc
			os.name          = Solaris
			java.vendor.url  = http://www.sun.com/
			user.dir         = /home2/zap/bin
			java.class.path  = /home2/docs/jde/JDK/classes:/home2/[...]
			java.class.version = 45.3
			os.version       = 2.x
			path.separator   = :
			user.home        = /export/home/michael
	verbose [false]
		Turn on [off] the display of trace messages from Zap and the Java 
		RemoteDebugger about their internal states.
	splash
		Display the Zap splash introduction message.
	noSplash
		Do not display the Zap splash introduction message automat-
		ically upon startup of the debugger. This command is typically 
		put in the 'zap.ini' command file.
	options
		Display the Zap command-line options.
	prompt [style]
		Specify style of debugger prompt to be one of:
			this
			location
			thread
			this+location
			thread+location
			none
		Examples:
			> prompt this
			<static>
			> prompt this
			(java.lang.String)0xee31a0d8>
			> prompt location
			[java.lang.String:55]>
	
			> prompt this+location
			(java.lang.String)0xee31a0d8[java.lang.String:55]>
			> prompt thread+location
			Thread-5[java.lang.String:55]>
			> prompt
			thread+location
			> prompt thread
			Thread-5>
			> prompt none
			>
	genEmacsInfo [false]
		Turn on [off] the generation of location information of interest 
		to Emacs. This information is used by Emacs to visually indicate 
		the current line of execution in the source code.
		This is some code that fools Emacs with a shell buffer running
		Zap into thinking it is talking to a gdb:
 
		(defun zap-mode ()
		  (interactive)
		  (require 'gdb)
		  (set-process-filter (get-buffer-process (current-buffer)) 'gdb-filter)
		  (set-process-sentinel (get-buffer-process (current-buffer)) 'gdb-sentinel)
		  (gdb-mode)
		  (gdb-set-buffer))
	use [path1:path2:...]
		Display or optionally specify the paths in which the debugger 
		will look for source code files. This source code is what is
		displayed at breakpoints, when the 'list' command is used,
		etc.
	CONTROL FLOW COMMANDS
	catch [name]
		Display or optionally specify exceptions that are caught. 
		Exceptions that are specified as caught will cause a 
		breakpoint when thrown. Exceptions that are not caught are 
		completely ignored and do not cause any visible behavior or 
		output. By default all exceptions are ignored.
		Examples:
			> catch java.lang.IllegalArgumentException
	ignore [name]
	Display or optionally specify exceptions that are caught. Exceptions
	that are specified as caught will cause a breakpoint when thrown. 
	Exceptions that are not caught are completely ignored and do not 
	cause any visible behavior or output. By default all exceptions
	are ignored.
	Examples:
		> catch java.lang.IllegalArgumentException
	threads
		Display information about all threads associated with the 
		debugged program.
	thread [name]
		Display or optionally specify the current thread. A running, 
		suspended or breakpointed program will typically have a number
		of associated threads. The 'where', 'up', 'down', 'next' and 
		'step' commands operate on the 'current thread'. The current 
		thread is specified by the 'thread' command or automatically 
		when a breakpoint or exception occurs.
		Examples:
			> thread Thread-5
	suspend [threadName | all]
		Suspend the current thread (the default), or optionally a 
		specified thread or all threads. Threads can later be resumed 
		by using the 'cont' or 'resume' commands.
	halt | break
		Suspend all threads. The threads can later be resumed by using
		the 'cont' or 'resume' commands.
	cont | resume [name|all]
		Resume running the current, specified or all threads. If the 
		current or specified thread is blocked waiting on another 
		suspended tread then it will not be resumed until the other 
		'waited upon' thread is resumed (either by it's own 'resume' 
		command or by using 'resume all').
	next
		Execute one source level instruction by the current thread, 
		stepping over any method calls.
	step
		Execute one source level instruction by the current thread, 
		stepping into any method calls.
	up [numberOfFrames]
		Change the debugger current stack frame to be that of the 
		caller of the current method, if any. This is repeated for 
		the specified number of frames (the default number of frames 
		to move up is one).  The commands like 'dump', 'locals', 
		'list' will now display information about the current frame. 
		The 'where' command will display the whole call stack at any 
		time.
	down [numberOfFrames]
		Change the debugger current stack frame to be that called by 
		the current method, if any. This is repeated for the number 
		of times specified (the default number of frames to move down 
		is one). The commands like 'print', 'locals', 'list' will now 
		display information about this current frame. The 'where' 
		command will display the whole call stack at any time.
	assign | set <variable> [=] <value>
		Assign the given value to the given variable.
		Examples:
			> assign x=1
			> assign y 2
			> set z = 3
		Caveats:
			This feature is new with the 1.0.2 JDK. However there 
			is still no way to assign values to Objects or Strings 
			or Array elements.
	DISPLAY COMMANDS
	where [numberOfFrames]
		Display information about all (or the specified number) of 
		frames in the call stack.
	dump | locals
		Display the variables and their value for the current stack 
		frame.
	whatis <variable>
		Display the type of the given variable.
	classes [searchSpec]
		Display the names of the currently loaded classes. The 
		searchSpec can be used to narrow the search. Which classes 
		are loaded depends on which code has been executed up to the 
		current point. A class may be loaded manually by using the 
		'load' command.
	methods [className]
		Display the names of the methods of the current (or specified) 
		class.
	load <className>
		Load the given class. This command actually tells the Java 
		interpreter which is executing the debugged program to load 
		the given class. This command will fail if the class is not 
		found in the classpath.
	print [-r] <variable | ...>
		Display information about the specified variable, address, 
		class, or thread. The type and address of the variable is 
		displayed. The -r option is used to display the contents of 
		the variable.
		Examples:
			/*********************/
			/* Printing a Thread */
			/*********************/
			> print main
			main = (sun.tools.debug.MainThread)0xee300dc0
			> print -r main
			main = (sun.tools.debug.MainThread)0xee300dc0
			{
			    name = "main"
			    priority = 5
			    threadQ = null
			    PrivateInfo = -280920608
			    eetop = -280920884
			    single_step = false
			    daemon = false
			    stillborn = false
			    target = null
			    group = (java.lang.ThreadGroup)0xee300bc8
			    agent = (sun.tools.debug.Agent)0xee300910
			    clazz = 0xee30fc08:class(jeo.Demo)
			    argv =  <error occurred>
			}
	
			/********************/
			/* Printing a Class */
			/********************/
			> print String
			String = 0xee300028:class(java.lang.String)
			> print -r String
			String = 0xee300028:class(java.lang.String)
			{
			 superClass = 
			    0xee300018:class(java.lang.Object)
			 interfaces =  None
			 loader = None
			    InternSet = null
			}
	
			/**********************/
			/* Printing a Literal */
			/**********************/
			> print hidden
			hidden = false
			/************************/
			/* Printing an Instance */
			/************************/
			> print offScreenGraphics
			offScreenGraphics = (sun.awt.motif.X11Graphics)0xee324bb8
			> print -r offScreenGraphics
	
			offScreenGraphics = (sun.awt.motif.X11Graphics)0xee324bb8
			{
			    pData = 2004464
			    foreground = null
			    font = null
			    originX = 0
			    originY = 0
			    image = (sun.awt.motif.X11Image)0xee324a70
			}
	memory
		Display amounts of used and free memory available to the 
		Java interpreter running the debugged program.
		Example:
			> memory
			Total: 1052664, Free: 207808
	class <className>
		Display or specify current class. The current class is used
		as the default class in the 'list' and breakpoint commands.
	func | method <methodName>
		Specify current method. This is usually used before the 'list'
		command in order to view the source code of a method.
		Example:
			[java.lang.Object:-1]> func GraphPanel.relax
			[GraphPanel:84]> list
			84     
			85   synchronized void relax() {
			86       for (int i = 0 ; i < nedges ; i++) {
			87           Edge e = edges[i];
			88           double vx = nodes[e.to].x - nodes[e.from].x;
			89           double vy = nodes[e.to].y - nodes[e.from].y;
			90           double len = Math.sqrt(vx * vx + vy * vy);
			91           double f = (edges[i].len - len) / (len * 3) ;
			92           double dx = f * vx;
			93           double dy = f * vy;
 
			[GraphPanel:94]> 
	list [start [end]]
		Display lines of source code in the current class. The 
		default starting line is the current line. The default ending 
		line is 10 lines after the start line.
	/[string]
		Search forward through the current source file for the given
		text string. If no string is specified then the previous 
		search string is used.
	?[string]
		Search backward through the current source file for the given
		text string. If no string is specified then the previous 
		search string is used.
	line
		Display the source code for the current line.
	file
		Display the current source code filename.
	BREAKPOINT COMMANDS
	stop in <[className.]methodName> [if <var> <condition> <value>]
		Set a breakpoint to stop execution on entry to the specified 
		method. If no class is specified the current class is used
		(see the 'class' command). 'var' can be any variable name.
		'condition' can be any one of: >, >=, =, ==, <=, < and !=.
		'value' can be a <number>, true, false, or <string>.
	stop at <[className:]lineNumber> [if <var> <condition> <value>]
		Set a breakpoint to stop execution at the specified line
		number. If no class is specified the current class is used
		(see the 'class' command). 'var' can be any variable name.
		'condition' can be any one of: >, >=, =, ==, <=, < and !=.
		'value' can be a <number>, true, false, or <string>.
	when at <[className:]lineNumber> <command>
		Execute the given command at specified line number in the
		given class. If no class is specified the current class is 
		used (see the 'class' command).
	clear | delete [# | all]
		Remove the breakpoints at the location where the last 
		breakpoint was encountered. 
		breakPointID
			Remove the breakpoint with given numerical ID (as 
			listed using the 'stop' or 'status' commands). 
		all
			Remove all breakpoints.
	enable [breakPointID | all]
		Enable (set) the breakpoints at the location where the last 
		breakpoint was encountered. 
		breakPointID
			Enable the breakpoint with given numerical ID (as 
			listed using the 'stop' or 'status' commands). 
		all
			Enable all breakpoints.
	disable [# | all]
		Disable (unset) the breakpoints at the location where the last 
		breakpoint was encountered. 
		breakPointID
			Disable the breakpoint with given numerical ID (as 
			listed using the 'stop' or 'status' commands). 
		all
			Disable all breakpoints.
	stop | status
		
		List all breakpoints, their ID and their state (either
		enabled or disabled).
	breakpoints [save | load]
		List all breakpoints, their ID and their state (either 
		enabled or disabled).
		save
			Save all breakpoints to a file (zap.brk).
		load
			Load all breakpoints from a file (zap.brk).
	SHELL COMMANDS
	alias [orig] [new]
		Display all aliases or add a new command name alias. Aliases
		are typically found in the zap.ini configuration file.
		Examples:
			alias l list
			alias si 'stop in'
	history [size]
		Display or resize history buffer. The history buffer maintains
		a copy of the last [size] zap debugger commands entered by the 
		user. The default size of the history buffer is 200.
	history save [fileName]
		Save history buffer to a file. The default filename is zap.hst.
	history load [fileName]
		Load history buffer from a file and execute it. The default
		filename is zap.hst.
	source [fileName]
		Load history buffer from a file and execute it. The default
		filename is zap.hst.
	!!
		Repeat last command.
	!<prevCmd# | prevCmd>
		Repeat a previous command. prevCmd# may be the numerical 
		index of any of the previous commands stored in the history 
		buffer as listed by the 'history' command. prevCmd may be the 
		first few characters of any of the previous commands stored 
		in the history buffer as listed by the 'history' command.
ENVIRONMENT
	The CLASSPATH and PATH environment variables need to be modified in 
	order for the zap debugger to run. Add 'Zap/classes' to the CLASSPATH 
	and 'Zap/bin' to the PATH environment variables.
FILES
	zap.ini
		This file contains zap debugger commands and is read and 
		executed when zap is started.  It is read first from the 
		current user's home directory and then from the local 
		directory. The commands in the (possibly) two files are 
		executed in order. This file typically contains a list of 
		alias commands and a sample is provided with Zap.
	zap.hst
		The default file used by the zap debugger 'history save' and 
		'history load' commands.
	zap.brk
		The default file used by the zap debugger 'breakpoints save' and 
		'breakpoints load' commands.
SEE ALSO
	The documentation for Sun's 'jdb' debugger and debug package 
	(sun.tools.debug.*).
NOTES
BUGS