FAQ

This FAQ addresses the following questions.  Please let me know of any FAQ you want added.

What does it do?
I do a putenv in a script, but when it finishes, and I do an 'env' command, it is not there.
How do I get the debug output of my command to the JVM standard list instead of the 'console'.
When I try to compile my command, I get "Unable to compile...".
I don't like that stupid prompt.  How do I change it?
When I enter my new command, all I get is "Unknown command".
I want a command to run in background.  How do I do that?
How do I stop my command prematurely?
Where is the help file that is displayed when I type in help?
How do I get extended help on an individual command or syntax?
I want to develop my own set of commands, what should I do first?
Do I have to extract the source for every command to do development on my own commands?
What commands are supposed to be available?


What does it do?

	So, here are just of few things that can be done.

	Compile, test, compile, test, and compile, test, your Java code without
	leaving the JVM.

	Pipe output from any command as input to any other command.

	Do automated testing by being able to pipe output between commands, so that
	conditions that cause a bug, can be easily reproduced, and diagnosed.  In
	a typical GUI environment this is very difficult, if not impossible.

	Unload classes so they can be updated, or free memory for
	resources you know will no longer be needed.

	Provides a pseudo terminal interface which uses the same look and feel
	regardless of which platform you are on, including file path nomenclature.


I do a putenv in a script, but when it finishes, and I do an 'env' command, it is not there.

	Since a script may change the current directory, and do puts to the environment,
	you would not want your environment to become so huge that it was taking up as much
	room as your total screen memory after weeks of having your jvm up and running.
	Add to that the unlikelyhood of having all scripts clean up their environment before
	they end, and you will see the appropriateness of implementing this behavior just
	like a C program environment, where any changes are inherited only by child processes.
	The same behavior is reproduced here.

	In order to place values in permanent environment space, use 'sysputenv', which affects
	System.getProperties().


How do I get the debug output of my command to the JVM standard list instead of the 'console'.

	The value for stdio.stderr, is set after the initialization script executes.
	Therefore, use 'pjda -noautoexec', then enter 'loadenv;console on' at the prompt.
	This will have the normal 'console on' during initialization not be done so that
	stdio.stderr gets set to the JVM $stdlist.


When I try to compile my command, I get "Unable to compile...".

	The function $resolveCommand(file), in whence.sh, assumes the current working directory
	at the time of starting the JVM (ie System.getProperty("user.dir")) is the top of the
	java package and class tree.  This assumption may be removed in the future, but to do
	so would require Sun changing how 'jar' works.  Currently -C only works for a single
	subsequent parameter.  This means that for each file listed, "-C" and "$CWD" must be
	inserted into the argument list.  In addition, there is no -x option which allows
	an alternate current directory to be specified for the purpose of defining extract
	behavior.  For these as well as other reasons, for the moment, this assumption will
	stay in place.  If you wish to participate in resolving these issues what is needed
	is a proper implementation of 'jar'.  'javac' already provides such methods as are
	necessary to compile any classes from any particular arbitrary directory via the
	specification of '-sourcepath'(set the local environment variable $java.source.path)


I don't like that stupid prompt.  How do I change it?

	To define the prompt to be something else, currently use
	-Dpjda.Prompt=somethingelse when you start the JVM, or define the value
	via sysputenv during initialization.  If a "$G" exists in the prompt, it is replaced
	by the current working directory.  The prompt is terminated by a hardcoded '%', but
	there is no code which assumes the prompt ends with a percent.  This is why the
	command 'send - ...' issues the prompt '>' and the code still works.  The reason for the
	'%' is to distinguish the end of the prompt from the ':' which separates prompt
	components.  Open a database, and note how the prompt changes.
	Rather than hard code the System Property to use, pjda.admin.Pjda uses its first
	package name component and appends ".Prompt", so you can change the package name
	and what will need to be set in the environment will be consistent with the new name.


When I enter my new command, all I get is "Unknown command".

	Assuming your command is 'mycommand', then does it have a proper package.class name
	nomenclature?  This will depend upon the CommandLocator used.  If it is a top level
	command then it should be named <somepackagename>.pjda.Command.<commandname>Command,
	where <somepackagename> is included in the System Property "pjda.Command.Path", which
	defines the list of prefix package names to be searched to find a given command.

	Does 'whence mycommand' return the right location?

	Does it implement the right interfaces(CommandInterface)?

	Does the class 'local' exist along with it in the same directory.

	See also "I want to develop my own set of commands, what should I do first?".


I want a command to run in background.  How do I do that?

	If you want a command to always run in background as a separate thread, then
	Implement the runnable interface, use the 'execute' method to define your arguments,
	then put the body of your command in the 'run' method.

	If instead, you want to run a command in background just this once, so to speak, then
	terminate the command line with an '&' just like in unix.


How do I stop my command prematurely?

	If your command is a normal command, then do a control C.
	If your command is a separate thread, then use the 'ps' and 'stopthread' commands.

	For normal command operation, the AWT thread is executing when you type the ^C.
	This means that the thread which gets the ^C is not the one you really want to interrupt.
	The 'console' 'interrupts' the thread which was last doing output.  During output to
	the 'console', if the current thread is 'interrupted()', then it throws a new Error("^C").
	This Throwable is trapped by the command interpreter, so the executing command is
	interrupted without having to check on the status itself.  The 'cp' command checks
	the status of interrupted() on a somewhat frequent basis, so even though it does not
	do any output to the 'console', it is still "interruptable".  Please note, that if you
	do not have the console enabled, and you are using the JVM $stdin, then the ^C will
	typically abort the JVM.


Where is the help file that is displayed when I type in help?

	There is no help file.  The list of commands and their descriptions is generated 
	live, whether coming from jars, or from disk.  Every class in every allowed package 
	which implements the helpInterface has its help(argv[]) method called.

	This way, the help is always up to date.  If a command is added, it must have a
	help method.  The help information is therefore always imbedded in the command class,
	so it is essentially self contained.

	Note also that while ?shell is available for help, there is no 'shell' command.
	That is because while Command.pjda.Command.shellCommand implements helpInterface, it
	does not implement CommandInterface, thereby making it not a valid command.


How do I get extended help on an individual command or syntax?

	To get extended help type either ?command, or 'command line?'.
	Currently no command checks the values of the arguments to determine help output,
	except whether it is null or not.  However, if the help method needs to know
	what the command arguments were to affect output, then the information is supplied.


I want to develop my own set of commands, what should I do first?


	First look at how the directory 'local' is layed out.
	Note how the directory 'Command', and 'JBase' are layed out as well.
	So, depending upon which kinds of commands you wish to implement, you would
	have a directory structure like this:

	<yourTopDirectory>
		pjda
			Command		/* this directory contains all your normal commands */
			JBaseCommand	/* this directory contains all JBase related commands */
			JBaseSetCommand	/* ...  You get the point */

	Then copy the java source file for class Command.pjda.Command.skeletonCommand to your
	Command directory above.
	Change only the package name and make sure it compiles.
	Then copy it to an appropriately named file.  Assuming this will be a normal command,
	we would copy it say 'mypjdatestCommand.java', open it in an editor, change the class
	name and constructor, take out the comments around the implements clause, add a return
	value to the help method, save it, and compile it.
	Good, just a few more things to do.
	execute these commands:
		sysputenv "pjda.Command.Path=$pjda.Command.Path$$;mystuff"
		sysputenv "pjda.Command.Jar.Path=mystuff;$pjda.Command.Jar.Path"
		clearclasscache
		?mypjdatest
	Notice that the help from your commands help method was displayed.  This shows that your
	command class was properly named, it implemented the appropriate interfaces, and is
	working fine.
	There is one more thing to do.  Because the 'help' command needs to list all classes in
	every directory where it is supposed to look, even directories which contain classes 
	that aren't used as commands, what is looked for is a single class in every package 
	which implements any commands.  This reduces the amount of overhead in the help 
	command.  Therefore, we need to do the following:
		copy the source file Command/pjda/Command/local.java to your Command directory,
		change the package name, then compile it.
	That's all it takes.
	Now if we type in 'help myp', all the packages are listed, with those commands that
	start with 'myp' being listed, including the one we just added, all without leaving
	the JVM.
	We can also use ':wordpad mypjdatest', and wordpad will pull up the right file, 
	so you don't have to remember which directories/packages contain which commands, 
	and you won't have to type ( and backspace ;-) ) so much.
	In addition, we can use 'javac mypjdatest', and the right package and class will be
	recompiled.  It knows where things are, and you don't have to tell it what it already
	knows.  :-)
	Hint: Do a "?addjartopath".
		

Do I have to extract the source for every command to do development on my own commands?

	No.  Simply specify the jar names which contain all of the packages and their classes
	for the commands you wish to be available, without extracting the source.
	For example, assume the following:
	pjda.Command.Jar.Path="Command;local;JBase;sh;my_sh;jgmail;<javalibdir>/tools"
	pjda.Command.Path="Command;local;JBase"
	For each component in pjda.Command.Jar.Path, the class pjda.pjutil.CommandLocator,
	expects to be able to locate a jar or directory so named using the java class path.
	Therefore if your java class path includes ".", and you have a file 'local.jar', as
	well as a directory named 'local', then it will assume you want to use the jar if
	your your initially loaded class came from a jar, or from the directory, if it did
	not.  If you only have one or the other, it will use it.  This is true for scripts
	as well.  You can have a jar of scripts or a directory of scripts, and the rules
	for which one takes precedence is the same.  This way, you can have your current
	testing version in standard class files, and your working version in jars.  This
	is why there is the script/bat file 'pjda', as well as 'pjdaforcejar'.
	The first one uses the default rules, and the second one forces the use of the
	jars when they are available.


What commands are supposed to be available?

	Here is the output from 'help', at the base level, as of 2000, Mar. 16.
	(Tomorrow it may be different ;-) )  ( it was :-) )

For Package:pjda.Command
For Package:Command.pjda.Command
adduser <user_name> - adds/modifies information for <user_name>.
alarm [list|reset|unload <file>|load <file>|delete <idx|title>]
at [mm/dd/yyyy] [hh:mm[:ss]] do <cmd>
atexit <cmd> - Upon normal termination, execute 'atexit' commands in reverse order.
calc <expr> - Displays value of an Integer expression.  See also DCALC.
cat <url_file_dir_list>
cd <directory>|<jar>|<url> - Change working directory.
clearclasscache - Clears class cache of previously cached command classes.
client <url> - Call a PJDA Server.
clone [command].
console on|off  Enables/Disables a BigTextArea for the PJDA Console.
cp [-walkhtml] <url_file_dir_list> <destfilename> - copies the contents of a URL to a local file.
cron <StdCronTabSpec[5]> do <cmd>
dcalc <expression> - Displays value of a Floating Point expression.
debug <Class> - Lists method, interfaces, objects ... for given class.
echo <text> - Echoes text to stdlist.
env - displays current working environment.
every hh:mm do <cmd>
exit - request jvm termination.
for <identifier> in [path][pattern|fname] do <cmd>
freememory - Displays Runtime.freeMemory().
grep [-<flags>] <perlRegExp> [path][pattern|fname]
help [-verbose] [-debug] <cmdStartsWith>  -   use ?<command>, to get specific help on <command>.
history - similar to Unix.
if <condition> then <cmd>
in hh:mm do <cmd>
interruptthread [threadidx]
introspect ['class'|'package' ['list'] ] <ClassName|CommandName> - Lists all methods, interfaces, objects ... for a given class(/package), or all classes in same package.
jar - Use standard JAR command options.
javac <classCommandList> - compiles classes and or commands listed.
jconsole on|off  Enables/Disables a jBigTextArea for the PJDA Swing Console.
loadenv [filename] - load into environment.
ls [path][pattern|fname]
mv <sourceList> <destFile>
ps - show thread and threadgroup information.
putenv <entry>=[<value>]
pwd - One line help for this command.
quit - forced termination.
r <[-]n|regexp> - redo prior command.
read <arguments> - sets environment variables(arguments) from Input Value.
rm [-R] [-f] <file|filelist|fileset>
saveenv [filename] - saves the current environment to given file.
server <servercmd>:<port>
shell - use '?shell' for a detailed list of shell functions and commands.
show <url|file>
signature [n:]passwordphrase[:<document|url>]
sleep <seconds> - Sleeps for <seconds>, then continues.
stopgroup [threadidx] -  stops the indicated group, if there is a way to do so.
stopthread [threadidx] [error|exception|interrupt] - attempts to stop, or throw Throwable, on the thread indicated.
sysenv - displays system environment.
sysputenv <entry>=[<value>] - puts(/removes) entry and value into the System environment.
totalmemory - Displays Runtime.totalMemory().
trace [on|off|commandName|className]
use <url|file>
wait - Waits until Enter(/or return) is pressed.
while <condition> do <cmd>
whileread <arguments> do <cmd> - sets environment variables(arguments) from Input Value.
For Package:local.pjda.Command
body - eat head and tail of Stdin.
encode <file> - prompts for password.  Use '?encode' for more info.
enmasse ... - issues an enmasse edit
entropy [filenamelist] - Calculate entry for files listed, or <Stdin>.
exportaol <aol.pfc> - attempts to export an AOL Personal Filing Cabinet to pastable NetScape BookMark format.
fontset <fontspec>.
listfont fontSpec - show font result after Font.decode($1).
listfonts - lists all current fonts.
localtest - Does my test code.
mergeoverlap <fileset> <tofile>
mkdir - Does my test code.
mytest - Does my test code.
notsed <fromString>=<toString> [...].
pop3 [host=<host>] [user=<user>] [pass=<pass>]
runtime <methodName> - Calls Runtime methods.
send <what> to <whom> [subject=<quotedSubject>] [attaching <fileList>[:encoded]]
system <methodName> - Calls System methods.
time - Displays System.currentTimeMillis() to Stdlist.
urlcheck [-walkhtml] <url_file_dir_list> - checks the contents of a URL for broken links.
validatenetscapebookmarks <bookmarkfile.htm>
wysiwyg - A WYSIWYG Editor
For Package:JBase.pjda.Command
changedb - interactive JBase alteration tool.
create <JBaseSchemaFile> - Creates the database specified in <JBaseSchemaFile>.
dbpurge <JBase> - Removes the LOCAL datasets and Root file for specified JBase.
erase <JBase> - erases the contents of the specified JBase.
jbasehelp [-verbose] - Displays help.
jbasetest - Does my test code.
load <JBUnloadFile> - reloads, an UNLOADED JBase from a JBUnload file.
open <jbase> - allows maintenance of a JBase database.
restore <JBStoreFile> - Restores JBase from a JBStore file.
store <JBase> [to <destFile>] - stores JBase database to a JBStore file.
unload <JBase> [to <destFile>] - Unloads database to JBUnload file.

	Once a database is opened, new commands become available.
	(look at the 'open' command.)
	Here is the output of help, after/when a database is opened.

For Package:local.pjda.JBaseCommand
encode [n:]passwordphrase[;<url>]
For Package:JBase.pjda.JBaseCommand
add <key>=<value>
delete <key>
dump
edit <setName>
encode [n:]passwordphrase[;<url>]
erase
find <keyValueList>
info
load <JBUnloadFile>
maintain <setName>
open <setname>
schema [<toFile>]
show [sets|items]
store [<destFile>]
trace [on|off]
unload <filespec>

	Even when 'help' shows only these commands, any of the previous layers
	commands still work, like 'cat', 'cp', and 'echo'.