
COMMANDS

	PSD accepts commands on the command line following the prompt.
	Commands are used for operations such as displaying help and exiting 
	PSD.


NOTATION

	The following notational conventions are used:

		*  In syntax descriptions, optional items are enclosed in
		   brackets ([]).

		*  Items that can be repeated one or more times are followed
		   by an ellipsis (...).

		*  Items that can be repeated zero or more times are enclosed
		   in brackets and followed by an ellipsis ([]...).

		*  A choice between items is indicated by seperating the items
		   with vertical bars (|).


COMMAND SUMMARY

	The following is summary of the available commands:

	!			Shell Escape
	base [number]		Display current base or set base to number
	bell [on | off]		Display or set error bell prompt on or off
	cbs number		Convert CBS format identifier to node number
	clear			Clear psd logfiles and the test counters
	continue		Set to continue on error
	DS_IP_ADDR [ip_addr]	Set DS_IP_ADDR environment variable
	empty [node]...		Set node configuration to EMPTY
	eval expression		Evaluate the expression and display in the 
				current base
	exit			Set to exit on error
	fill [node]...		Set node configuration to default
	first [node]		Set/display first node number
	getenv variable		Display the environment variable value
	halt			Set to halt on error
	help [category]		List available help or specific help 
				information. Categories are commands,
				tests, and utilities.
	himargin		Enable all cabinet high voltage margin
	ignore [num]...		Display ignored tests or ignore test number(s)
	last [node]		Set/display last node number
	level			Display current error message level
	log [default|error]	Display default and/or error log file(s)
	lomargin 		Enable all cabinets' low voltage margin
	ltu			Enable / Disable usage of ltu for message
				network tests.
	node node		Display node location in cbs format
	normal			Set error message level to normal
	OUR_IP_ADDR [ip_addr]	Set/display bootnode ip address
	prompt [level]		Set user prompt level
	pwm			Print Working Menu 
	quit			Exit to shell
	recognize [number]...	Display recognized tests or recognize test 
				number(s)
	reset			Perform software reset
	run command		Execute command
	scan [time]		Display or set scan channel timeout to number
	setenv name val		Set DTX environment variable
	silent			Set error message level to silent
	terse			Set error message level to terse
	unmargin 		Disable all cabinets' voltage margining
	unsetenv variable	Clear DTX environment variable
	verbose			Set error message level to verbose
	version			Display program version
	which [file]...		Display file location

	where expression, level, number, and node are mathematical expressions.


COMMAND DESCRIPTIONS

	The remainder of this file contains descriptions the commands.
	The commands are listed alphabetically.


NAME
	!

SYNOPSIS
	! [UNIX command]

DESCRIPTION
	The ! (bang) passes the given command to the UNIX shell for execution.

	For example,

	!ls -l

	passes the ls -l command to the UNIX shell which displays the contents
	of the current directory.

	The command,

	!csh

	is used to enter the UNIX C-Shell while running PSD.


NAME
	base

SYNOPSIS
	base [number]

DESCRIPTION
	The base command controls the base used to display the result of an 
	eval command.  Without an argument, base displays the current base 
	value. With an argument, base set the base value to the given number.
	Valid base numbers are 2 (binary), 8 (octal), 10 (decimal), and 16
	(hexadecimal).

	For example,

	base

	displays the current base value.

	To change the base value to hexadecimal, enter the command:

	base 16

	Note that base only controls the output of an eval command.  All other
	input and output is unchanged.  Input defaults to decimal (base 10) but
	can be overridden by prefixing the number with a conversion control.
	Conversion controls are 0b for binary (base 2), 0 for octal (base 8),
	and 0x for hexadecimal (base 16).  In addition, the character k can be
	suffixed on a decimal number to indicate a multiplier of 1024.

	See also: eval.


NAME
	bell

SYNPOSIS
	bell [on | off]

DESCRIPTION
	The bell command displays or sets the error message bell prompt.
	Setting the error message bell prompt on will cause the terminal bell
	to sound when an error occurs. Without an argument, bell displays the
	current mode and prompts the user to change the mode. With an argument,
	the bell prompt is set to the given mode. Valid modes are on (enable 
	error message bell prompt) and off (disable error message bell prompt).

	For example,

	bell

	displays the current error message bell prompt mode.

	To turn the error message bell prompt off, enter the command:

	bell off

	The default error message bell prompt mode is on.

	See also: level, silent, terse, verbose.



NAME
	cbs

SYNOPSIS

	cbs [number]

DESCRIPTION
	
	The cbs command converts a Cabinet, Backplane, Slot notation of a
	node number to a linear node number. In cbs, c represents the cabinet
	number, b represents the backplane number and s represents the slot
	number. C is shown as a two digit number, b is shown as an alpha
	value between A to D and s is shown as a two digit number.

	For example,

	cbs 00B02

	returns the following:

	Cabinet 0, Backplane B, Slot 2 is node number 18.
	


NAME
	clear

SYNOPSIS
	clear

DESCRIPTION
	The clear command is used to set all test counters to zero and to 
	remove the log files.  This command removes both default and error
	logfiles.

	The default logfile contains messages sent to both stdout and stderr.
	Whereas, the error logfile only contains messages sent to stderr.

	For example,

	clear

	clears both the default and error log files and resets the test 
	counters

NAME
	continue

SYNOPSIS
	continue

DESCRIPTION
	The continue command allows PSD to continue on error, thus permitting
	the next test or iteration to execute.  By default, PSD will stop test
	execution when an error occurs (halt on error).

	The continue command also controls the manner in which error messages
	are displayed. By default, error messages are paginated on the console.
	However, when continue on error is enabled, pagination is turned off
	and error messages simply scroll on the console.

	Continue on error is useful for diagnosing intermittent failures.  By
	setting PSD to continue on error, several errors may accumulate in the
	error log file while the system is unattended.  Later, the test can be
	stopped and the error log examined to isolate the cause of the failure.

	See also: exit, halt.


NAME
	DS_IP_ADDR

SYNOPSIS
	DS_IP_ADDR

DESCRIPTION
	DS_IP_ADDR sets/displays the environment variable which is also
	named DS_IP_ADDR. This variable represents the ip address of the
	diagnostic station. When typed in, this command displays the current
	value of the variable. It then prompts the user to either type in 
	a new value or hit return to continue.

	For example,

	DS_IP_ADDR

	will print on the display:

	DS_IP_ADDR is set to aa.bb.cc.dd (some interlnet address)
	Enter new DS_IP_ADDR or return:

See Also:
	OUR_IP_ADDR

	
NAME
	empty

SYNOPSIS
	empty [node]...

DESCRIPTION
	The empty command allows the user to set specified node configuration
	to EMPTY.  A node configured as EMPTY is not used during PSD tests.
	This change applies only within PSD and does not affect the
	/usr/paragon/boot/SYSCONFIG.TXT configuration file.  This command has
	no affect on nodes which are already configured as EMPTY.

	For example,

	empty 5

	configures node 5 as EMPTY.

	Configuring a slot as EMPTY is sometimes useful in failure isolation or
	as a workaround.  However, it is always a safer practice to physically
	remove the node from the slot in question.

	See also: conf, fill, slot.


NAME
	eval

SYNOPSIS
	eval expression

DESCRIPTION
	The eval command evaluates the given expression and displays the result
	in the current base (refer to the base command for more information).
	The following constructions are recognized:

	number      the value of number (this is the simplest expression)
	e1 + e2     expression 2 is added to expression 1
	e1 - e2     expression 2 is subtracted from expression 1
	e1 * e2     expression 1 is multiplied by expression 2
	e1 / e2     expression 1 is divided by expression 2
	e1 % e2     modulo expression 1 by expression 2
	e1 & e2     bitwise AND expression 1 and expression 2
	e1 | e2     bitwise OR expression 1 and expression 2
	e1 ^ e2     bitwise XOR expression 1 and expression 2
	e1 << e2    left shift expression 1 by expression 2
	e1 >> e2    right shift expression 1 by expression 2
	-e          negate expression
	~e          one's complement expression
	(e)         parentheses may be used to modify precedence

	Precedence is the same as the C programming language.

	See also: base.


NAME
	exit

SYNOPSIS
	exit

DESCRIPTION
	The exit command allows PSD to exit on error.  By default, PSD will
	stop test execution when an error occurs (halt on error).  If exit on
	error is set, PSD will display and log the error, then exit.

	Exit on error is useful when running PSD from a shell script.  If PSD
	executes without an error, the exit code is zero.  If an error has
	occurred, the exit code is -1.

	See also: continue, halt, quit.


NAME
	fill

SYNOPSIS
	fill [node]...

DESCRIPTION
	The fill command allows the user to set specified node configuration to
	its default.  The default node configuration is the configuration
	currently know by PSD for the node.  This change applies only within 
	PSD and does not affect the /usr/paragon/boot/SYSCONFIG.TXT 
	configuration file. This command has no affect on nodes which have a
	default configuration of EMPTY.

	For example,

	fill 5

	configures node 5 with its default.

	See also: conf, empty, slot.


NAME
	first

SYNOPSIS
	first [node]

DESCRIPTION
	The first command allows the user to specify the first node in the
	system to begin testing.  Nodes in the system less than the first 
	node number are not tested.  The default first node is determined by
	the /usr/paragon/boot/SYSCONFIG.TXT file.  This change applies only
	within PSD and does not affect the /usr/paragon/boot/SYSCONFIG.TXT 
	configuration file.

	When called without an argument this command displays the first
	node number in the system.

	For example,

	first 5

	sets the first node in the system to be node 5.

	See also: last.


NAME
	getenv

SYNOPSIS
	getenv variable

DESCRIPTION
	getenv command gets the value corresponding to the variable
	environment variable. The value is printed on the screen.

	See also setenv, unsetenv

NAME
	halt

SYNOPSIS
	halt

DESCRIPTION
	The halt command allows PSD to halt on error, thus preventing the next
	test or iteration from executing.  By default, PSD will stop test
	execution when an error occurs (halt on error).

	The halt command also controls the manner in which error messages are
	displayed.  When continue on error is enabled, pagination is turned off
	and error messages simply scroll on the console.  However, when halt on
	error is enabled, pagination is turned on.

	See also: continue, exit.


NAME
	help

SYNOPSIS
	help [category]

DESCRIPTION
	The Help Facility provides assistance for users, whether they desire
	general information or specific assistance.  Without an argument, help
	prints a list of available on-line assistance categories.  With an
	argument, help directly displays the named on-line assistance category.
	Help is available for several categories.

	For example,

	help commands

	displays this help information.

	The following is recommended for first time users:

	help intro


NAME
	himargin

SYNOPSIS
	himargin

DESCRIPTION
	The himargin command enables high voltage margin on all cabinets in
	the system. The himargin value is currently set to 2% higher than
	the nominal voltage.

	See also: lomargin, unmargin

NAME
	ignore

SYNOPSIS
	ign[ore] [number]...

DESCRIPTION
	The ignore command prevents a test from executing during a test zero
	(run all tests) sequence.  Ignoring a menu prevents subtests under that
	menu from executing.  Without arguments, ignored tests are displayed
	from the current menu and below.  By entering a specific test number or
	list of test numbers, tests are ignored.

	For example,

	ignore

	displays the ignored tests from the current menu level down.

	To ignore test numbers three, five, and seven, enter the following
	command:

	ignore 3 5 7

	See also: recognize.


NAME
	last

SYNOPSIS
	last [node]

DESCRIPTION
	The last command allows the user to specify the last node in the system
	to end testing.  Nodes in the system greater than the last node number
	are not tested.  The default last node is determined by the
	/usr/paragon/boot/SYSCONFIG.TXT file.  This change applies only within
	PSD and does not affect the /usr/paragon/boot/SYSCONFIG.TXT 
	configuration file.

	When called without an argument this command displays the last
	node number in the system.

	For example,

	last 50

	sets the last node in the system to be node 50.

	See also: first.


NAME
	level

SYNOPSIS
	level

DESCRIPTION
	The level command displays a message indicating the error reporting
	level.  Four error reporting levels are available as described below:

	* silent No errors are reported.

	* terse The name of the failing test is reported and timestamped.

	* normal In addition to the terse error message, an error message
	  describing the cause of the failure is reported.

	* verbose In addition to the normal error message, more detailed error
	  information is reported.

	The default error reporting level is normal.  The silent level provides
	the fastest test execution but no diagnostic capability.  The verbose
	level provides the most detailed error messages.  Both silent and
	verbose levels are used primarily by Engineering and Manufacturing
	personnel.

	See also: bell, normal, silent, terse, verbose.


NAME
	log

SYNOPSIS
	log [ default | error ]

DESCRIPTION
	There are two logfiles in psd. The default logfile (callled psd.def) 
	logs all messages sent to the stdout and stderr. The error logfile 
	(called psd.log) contains only messages that are sent to stderr. The
	log command displays log files using the UNIX less command.

	When log is invoked without any argument, then both logfiles are 
	displayed. A specific logfile is displayed when an argument is passed 
	to the command.

	See also: clear.


NAME
	lomargin

SYNOPSIS
	lomargin

DESCRIPTION
	The lomargin command enables low voltage margin on all cabinets in
	the system. The lomargin value is currently set to  2% less than the 
	nominal voltage.

	See also: himargin, unmargin


NAME
	ltu

SYNOPSIS
	ltu

DESCRIPTION
	This command displays the current mode of the Line Transfer Unit (LTU)
	as used by the Message Network Tests. The LTU is either in Enable 
	state which means LTU is used for data transfer. Otherwise, the
	LTU is in Disable state which means data is transfered using CPU
	control.

NAME
	node

SYNOPSIS
	node [node]

DESCRIPTION
	The node command displays the location of the given node.  It's 
	location is described in cbs format.

	For example,

	node 5

	displays the following message on the console:

	Node 5 is located in Cardcage 0 Slot 5


NAME
	normal

SYNOPSIS
	normal

DESCRIPTION
	The normal command sets the error message reporting level to normal.
	The normal error reporting level displays the name of the failing test,
	a timestamp, and an error message describing the cause of the failure.
	This is the default error message reporting level.

	See also: bell, level, silent, terse, verbose.

NAME
	OUR_IP_ADDR

SYNOPSIS
	OUR_IP_ADDR

DESCRIPTION
	OUR_IP_ADDR sets/displays the environment variable which is
	named OUR_IP_ADDR. This variable represents the ip address of the
	bootnode. When typed in, this command displays the current
	value of the variable. It then prompts the user to either type in 
	a new value or hit return to continue.

	For example,

	OUR_IP_ADDR

	will print on the display:

	OUR_IP_ADDR is set to aa.bb.cc.dd (some interlnet address)
	Enter new OUR_IP_ADDR or return:

See Also:
	DS_IP_ADDR


NAME
	prompt

SYNOPSIS
	prompt level

DESCRIPTION
	This command sets the environment variable PROMPT with the integer
	value level. The PROMPT variable is interpreted by different test
	programs to determine what level of prompting is required by the
	user.


NAME
	pwm

SYNOPSIS
	pwm

DESCRIPTION
	The pwm command displays the path from Root Menu to the current menu.
	This command is similar to the UNIX pwd command.


NAME
	quit

SYNOPSIS
	q[uit]

DESCRIPTION
	The quit command closes all open files and returns control to the UNIX
	operating system.  If PSD has executed without an error, the exit code
	is zero.  If an error has occurred, the exit code is -1.

	See also: quit.


NAME
	recognize

SYNOPSIS
	rec[ognize] [number]...

DESCRIPTION
	The recognize command allows a to test execute during a test zero (run
	all tests) sequence.  Recognizing a menu allows recognized subtests
	under that menu to execute.  Without arguments, recognized tests are
	displayed from the current menu and below.  By entering a specific test
	number or list of test numbers, tests are recognized.

	For example,

	recognize

	displays the recognized tests from the current menu level down.

	To recognize test numbers three, five, and seven, enter the following
	command:

	recognize 3 5 7

	See also: ignore.


NAME
	reset

SYNOPSIS
	r[eset]

DESCRIPTION
	The reset command performs a software reset to set the system back to a
	known state.  The software reset closes and opens the serial channel 
	and sets the internal software state machine to an invalid state.  
	This command should be executed if the system power is cycled and PSD 
	is not re-invoked.  Closing and opening the scan channel will flush any
	erroneous characters which may be received when the system power is
	cycled.  Setting the software state machine to an invalid state will
	cause the nodes to be automatically reset and initialized as required
	by each test.


NAME
	run

SYNOPSIS
	run a.out

DESCRIPTION
	This command executes the executable file identified by `a.out'. 


NAME
	scan

SYNOPSIS
	scan [timeout]

DESCRIPTION
	The scan command displays or sets the scan channel timeout.  The scan
	channel timeout is the maximum time for a character to be received on
	the console from the scan channel.  This timeout is in seconds and must
	be greater than the mesh channel timeout.  The default timeout is six
	seconds.

	For example,

	scan 8

	sets the scan channel timeout to eight seconds.



NAME
	setenv

SYNOPSIS
	setenv NAME val

DESCRIPTION
	Sets the value of environment variable, NAME, to value identified by
	val.

	For example,
	
	setenv COUNT 15,

	will set the environemt variable COUNT to 15.

	See also: unsetenv, getenv.

	
NAME
	silent

SYNOPSIS
	silent

DESCRIPTION
	The silent command sets the error message reporting level to silent.
	The silent error reporting level does not report errors and therefore
	provides no diagnostic capability.  This level provides the fastest 
	test execution and is used primarily by Engineering and Manufacturing
	personnel.

	See also: bell, level, normal, terse, verbose.


/***  XXX NEED TO REMOVE ***/
NAME
	summary

SYNOPSIS
	sum[mary] [passed | failed | executed | not executed]

DESCRIPTION
	The summary command displays a table showing the number of trials and
	failures of tests matching the given condition.  The default condition
	is all tests which have failed.

	For example,

	sum

	displays a summary of all tests which have failed.

	To display a summary of all tests which have executed, enter the
	command:

	sum executed

	See also: clear.


NAME
	terse

SYNOPSIS
	terse

DESCRIPTION
	The terse command sets the error message reporting level to terse.  The
	terse error reporting level displays only the name of the failing test
	and a timestamp.

	See also: bell, level, normal, silent, verbose.


NAME
	unmargin

SYNOPSIS
	unmargin

DESCRIPTION
	The unmargin command disables voltage margin on all cabinets in
	the system. In other words, it sets the power supply to nominal
	voltage.

	See also: himargin, lomargin


NAME
	unsetenv

SYNOPSIS
	unsetenv NAME

DESCRIPTION
	unsets the value of the environment variable whose name is NAME. 

	For example,

	unsetenv COUNT,

	will unset the value of environment variable COUNT.

	See also: setenv, getenv.

NAME
	verbose

SYNOPSIS
	verbose

DESCRIPTION
	The verbose command sets the error message reporting level to verbose.
	The verbose error reporting level displays the name of the failing
	test, a timestamp, and an error message describing the cause of the
	failure, and detailed error information.  This level is used primarily
	by Engineering and Manufacturing personnel.

	See also: bell, level, normal, silent, terse.


NAME
	version

SYNOPSIS
	version

DESCRIPTION
	The version command displays the PSD version number.


NAME
	which

SYNOPSIS
	which filename

DESCRIPTION
	which command locates a file and displays its full pathname. The
	search recursively descends in the directory hierarchy starting the
	current directory name.





