} // public void NormalExit (1 of 8)
/// <summary>
/// Exit the program normally, optionally returning a nonzero status
/// code. If running in debug mode, use WaitForCarbonUnit to block until
/// the tester has a chance to read the output or capture it into the
/// clipboard.
/// </summary>
/// <param name="puintStatusCode">
/// This unsigned integer specifies the program's exit code.
/// </param>
/// <param name="pstrOperatorPrompt">
/// This string specifies an alternative message for method
/// WaitForCarbonUnit to display. If this is an empty string or null
/// reference, a default message, "Please press the ENTER (Return) key
/// to exit the program." is shown.
/// </param>
/// <remarks>
/// This is the original implementation, since pre-empted by the simpler
/// method call that takes no arguments.
///
/// When I implemented the #if DEBUG conditional compilation block, I
/// didn't take into consideration that the only time that #if DEBUG is
/// true is when the debug version of this library is built. I decided
/// to leave it in, as a reminder to myself of how it can be effectively
/// used with some of the new overloads.
/// </remarks>
public void NormalExit (
uint puintStatusCode ,
string pstrOperatorPrompt )
{
this.DisplayEOJMessage ( );
if ( System.Diagnostics.Debugger.IsAttached )
{
if ( puintStatusCode != MagicNumbers.ERROR_SUCCESS )
Console.WriteLine (
Properties.Resources.CONSOLE_APP_EXIT_CODE ,
puintStatusCode ,
Environment.NewLine );
} // if ( System.Diagnostics.Debugger.IsAttached )
DisplayAids.WaitForCarbonUnit ( pstrOperatorPrompt );
Environment.Exit ( ( int ) puintStatusCode );
} // public void NormalExit (2 of 8)
} // public void DisplayEOJMessage method
#endregion // BOJ and EOJ Message Displays
#region ErrorExit Methods
/// <summary>
/// Display an error message, read from a table of static strings, and
/// exit, returning the exit code. See Remarks.
/// </summary>
/// <param name="puintStatusCode">
/// This unsigned integer specifies the subscript of the message, and it
/// becomes the program's exit code. See Remarks.
/// </param>
/// <remarks>
/// You must supply the messages as an array of strings, by calling
/// instance method LoadErrorMessageTable.
///
/// After the message is displayed, static method WaitForCarbonUnit
/// is called with a null string reference, causing it to display its
/// default prompt, and wait until an operator presses the RETURN key.
///
/// When WaitForCarbonUnit returns, the DisplayEOJMessage method on the
/// singleton instance is called to display the end of job message,
/// along with the ending time and elapsed time, and control is returned
/// to the OS, sending along the exit code.
/// </remarks>
public void ErrorExit ( uint puintStatusCode )
{
if ( _me.AppErrorMessages != null )
{
if ( puintStatusCode < _me.AppErrorMessages.Length )
{
Console.WriteLine (
_me.AppErrorMessages [ puintStatusCode ] );
} // TRUE (expected outcome) block, if ( puintStatusCode < _me.AppErrorMessages.Length )
else
{
Console.WriteLine (
Properties.Resources.ERRMSG_UNKNOWN_EXIT_CODE ,
puintStatusCode );
} // FALSE (UNexpected outcome) block, if ( puintStatusCode < _me.AppErrorMessages.Length )
Console.WriteLine (
Properties.Resources.CONSOLE_APP_EXIT_CODE ,
puintStatusCode ,
Environment.NewLine );
} // if ( _me.AppErrorMessages != null )
this.DisplayEOJMessage ( );
if ( System.Diagnostics.Debugger.IsAttached )
DisplayAids.WaitForCarbonUnit ( null );
else if ( puintStatusCode > MagicNumbers.ERROR_SUCCESS )
DisplayAids.TimedWait (
TIMED_WAIT_DEFAULT_SECONDS , // uint puintWaitSeconds
TIMED_WAIT_WAITING_FOR_DEFAULT , // string pstrCountdownWaitingFor
TIMED_WAIT_TEXT_COLOR_DEFAULT , // ConsoleColor pclrTextColor
TIMED_WAIT_BACKGROUND_COLOR_DEFAULT , // ConsoleColor pclrTextBackgroundColor
TIMED_WAIT_INTERRUPT_CRITERION ); // InterruptCriterion penmInterruptCriterion
Environment.Exit ( ( int ) puintStatusCode );
} // public void ErrorExit
} // public void NormalExit (7 of 8)
/// <summary>
/// Exit the program normally, optionally returning a nonzero status
/// code, and optionally calling WaitForCarbonUnit to suspend execution
/// until the operator has a chance to read the output or capture it
/// into the clipboard.
/// </summary>
/// <param name="puintStatusCode">
/// This unsigned integer specifies the program's exit code.
/// </param>
/// <param name="pstrOperatorPrompt">
/// This string specifies an alternative message for method
/// WaitForCarbonUnit to display. If this is an empty string or null
/// reference, a default message, "Please press the ENTER (Return) key
/// to exit the program." is shown.
/// </param>
/// <param name="penmNormalExitAction">
/// This member of the NormalExitAction enumeration controls whether to
/// use WaitForCarbonUnit to suspend execution until an operator has a
/// chance to read the output. See the NormalExitAction enumeration for
/// details.
/// </param>
/// <param name="puintSecondsToWait">
/// Specify the number of seconds to wait, which must be a whole number
/// greater than or equal to zero. Setting this value to zero causes the
/// method to wait for 30 seconds.
/// </param>
/// <param name="pstrCountdownWaitingFor">
/// Specify the text to display along with the remaining time. If this
/// argument is null (Nothing in Visual Basic) or the empy string, the
/// method uses a default message.
///
/// Currently, the default description is "Program ending," which is
/// taken from a resource string in the WizardWrx.ConsoleAids class that
/// implements this feature.
/// </param>
/// <param name="pclrTextColor">
/// Specify a member of the ConsoleColor enumeration to control the text
/// color used to display the countdown message.
///
/// To use the default (current) screen colors, specify the same
/// ConsoleColor value for pclrTextColor and pclrTextBackgroundColor.
/// </param>
/// <param name="pclrTextBackgroundColor">
/// Specify a member of the ConsoleColor enumeration to control the
/// background color used to display the countdown message.
///
/// To use the default (current) screen colors, specify the same
/// ConsoleColor value for pclrTextColor and pclrTextBackgroundColor.
/// </param>
/// <param name="penmInterruptCriterion">
/// Specify a member of the DisplayAids.InterruptCriterion enumeration
/// to indicate whether you want the timed wait to be interruptible, and
/// under what conditions.
/// </param>
/// <remarks>
/// This method differs sufficiently from overload 2 that it stands on
/// its own. Theoretically, every other overload could call this one.
/// </remarks>
public void NormalExit (
uint puintStatusCode ,
string pstrOperatorPrompt ,
NormalExitAction penmNormalExitAction ,
uint puintSecondsToWait ,
string pstrCountdownWaitingFor ,
ConsoleColor pclrTextColor ,
ConsoleColor pclrTextBackgroundColor ,
DisplayAids.InterruptCriterion penmInterruptCriterion )
{
if ( penmNormalExitAction != NormalExitAction.Silent )
{
this.DisplayEOJMessage ( );
} // if ( penmNormalExitAction != NormalExitAction.Silent )
switch ( penmNormalExitAction )
{
case NormalExitAction.ExitImmediately:
case NormalExitAction.Silent:
Environment.Exit ( ( int ) puintStatusCode );
break;
case NormalExitAction.Timed:
Console.WriteLine ( pstrOperatorPrompt );
DisplayAids.TimedWait (
puintSecondsToWait , // puintWaitSeconds
pstrCountdownWaitingFor , // pstrCountdownWaitingFor
ConsoleColor.Black , // pclrTextColor
ConsoleColor.Black , // pclrTextBackgroundColor
penmInterruptCriterion ); // penmInterruptCriterion
Environment.Exit ( ( int ) puintStatusCode );
break;
case NormalExitAction.HaltOnError:
if ( puintStatusCode == MagicNumbers.ERROR_SUCCESS )
{ // No news is good news. Keep going.
Environment.Exit ( MagicNumbers.ERROR_SUCCESS );
} // TRUE block, if ( puintStatusCode == MagicNumbers.ERROR_SUCCESS )
else
{ // There was an error. Halt the script.
DisplayAids.WaitForCarbonUnit ( pstrOperatorPrompt );
Environment.Exit ( ( int ) puintStatusCode );
} // FALSE block, if ( puintStatusCode == MagicNumbers.ERROR_SUCCESS )
break;
case NormalExitAction.WaitForOperator:
DisplayAids.WaitForCarbonUnit ( pstrOperatorPrompt );
Environment.Exit ( ( int ) puintStatusCode );
break;
default:
Console.WriteLine (
Properties.Resources.NORMAL_EXIT_INTERNAL_ERROR , // Message template
penmNormalExitAction , // Token 0
NormalExitAction.WaitForOperator , // Token 1
Environment.NewLine ); // Token 2
DisplayAids.WaitForCarbonUnit ( pstrOperatorPrompt );
Environment.Exit ( ( int ) puintStatusCode );
break;
} // switch ( penmNormalExitAction )
} // public void NormalExit (8 of 8)
