INTRODUCTION

	The Paragon System Diagnostic (PSD) executes tests on the individual
	node boards and the communication links in the Paragon system.  When
	a failure is detected, an error message is reported to help isolate
	the failure to the defective part.


INVOCATION

	PSD may be invoked as follows:

	psd [-l logfile] [-m macfile] [-d default_file] [-e env_file]

	where
	    logfile is a user-specified error log file name.
	    The default error log file name is "psd.log".

	    macfile is a user-specified macro command file name.
	    The default macro command file name is ".psd.mac".

	    default_file is a user-specified error and information
	    log file name.  The default log fileis "psd.def".

	    env_file is a user-specified environment file name.
	    The default environment file name is "psdenv".


OPERATION

	When PSD is invoked, the "/usr/paragon/boot/SYSCONFIG.TXT" 
	configuration file is read.  This file contains information 
	describing the system under test.  The root menu is then displayed 
	followed by the command prompt.  By entering menu item numbers, the 
	menu tree may be examined and tests may be executed.

	In addition to the error log file, PSD also generates
        "/u/paragon/diag/psd.def" (referred to as the default log file).
	This file logs the progress of the PSD session.

	The default log file is useful when the diagnostics have been
	left running for a long time and later the operator wants to 
	check how the psd session proceeded.

	Following is a list of items that are captured in the default
	log file:

	    1.  It logs the trial count and the test name which is 
		being executed.
	    2.  All messages printed out by the tests programs are captured.
	    3.  It captures all error log messages (which are also available
                in the error log file).
	    4.  Almost all messages in this file are time stamped.  The only
	        non-time stamped messages may come from test programs which
	        can override the default time stamping.

	Similar to the error log file, the default log file is also backed
	up by psd when it is invoked.  The backup file is named
	"psd.def.bak".  The operator must rename this file if the log
	information is to be used in the future.

  NOTE: Due to elaborated logging in the default log file, the file
	size can grow substantially.  Make sure you have enough device
	space to accommodate this file.

	The default for all numbers entered in PSD is decimal or base 10.  This
	input default may 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.


TEST ZERO

	At any menu, a special menu item not displayed may be executed.  This
	item, called "test zero", is executed by entering a "0" at the command
	prompt.  A zero entry will cause PSD to execute all recognized tests
	from the current menu level down.  Utilities and ignored menus and 
	tests are not executed.


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 (|).


ERROR MESSAGSE

    When a test fails, a diagnostic error message will be displayed on the
    console and logged in the log file unless the error reporting level is
    set to silent (see commands).  The error message reporting level controls
    the amount of error message which is displayed.  By default PSD is set to
    report normal error messages.  The format of the error message is shown
    below:

        +++ <Test Suite> <version>
        <start date and time> ... <elapsed test time>
        [Trail #] <name of test>
        <error message>

    In the silent error message reporting level, no errors are reported.
    This level is useful for Engineering and Manufacturing personnel as it
    provides the fastest test execution but no diagnostic capability.  In
    the terse error message reporting level, only the first two lines of the
    error message are displayed.  For more information on error messages and
    reporting levels, see commands.

    By default, PSD will halt test execution when an error occurs.  Setting
    PSD to continue on error (see commands) will allow PSD to continue
    executing the next iteration of the test.  This is useful for diagnosing
    intermittent failures as it allows several errors to 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.

