Base interface for all system tools. See IOpticalSystemTools for access to specific tools. More...

Inheritance diagram for ZOSAPI.Tools.ISystemTool:

Public Member Functions
bool	Run ()
	Start the tool. Note that for synchronous tools (see IsAsynchronous), this call will block until completion. If it is asynchronous it will start running but return immediately.

bool	RunAndWaitForCompletion ()
	Sames as calling Run followed by WaitForCompletion.

bool	WaitForCompletion ()
	Waits for the asynchronous tool to complete.

bool	Cancel ()
	Cancels the currently running asynchronous tool.

bool	Close ()
	Closes this tool and frees up and associated resources.

RunStatus	WaitWithTimeout (double timeOutSeconds)
	Waits for the currently running tool to complete, with a specified time out value. Note that if the timeout is exceeded this method will return, however the tool will continue to run. Also note that this method will not start the tool running if it is not already.

RunStatus	RunAndWaitWithTimeout (double timeOutSeconds)
	Starts the tool running, and waits for it to complete with the specified timeout value. Note that if the timeout is exceeded this method will return, however the tool will continue to run.

Properties
int	Progress `[get]`
	Gets the progress of the current tool, if supported.

string	Status `[get]`
	Gets the status of the current tool, if supporoted.

bool	IsRunning `[get]`
	Gets a value indicating whether the tool is currently running asynchronously.

bool	CanCancel `[get]`
	Gets a value indicating whether the tool can be cancelled.

bool	IsAsynchronous `[get]`
	Gets a value indicating whether the tool runs asynchronously (i.e. on a thread).

bool	IsFiniteDuration `[get]`
	Gets a value indicating whether this tool will complete on its own.

bool	IsValid `[get]`
	Gets a value indicating whether the input settings are valid.

bool	Succeeded `[get]`
	Gets a value indicating whether the tool execution succeeded.

string	ErrorMessage `[get]`
	If Succeeded is `false`, get the error messages; otherwise, `null`.

Detailed Description

Base interface for all system tools. See IOpticalSystemTools for access to specific tools.

Member Function Documentation

◆ Cancel()

bool ZOSAPI.Tools.ISystemTool.Cancel ( )

Cancels the currently running asynchronous tool.

Usage (see Example 03 for a full sample)

C#

            // Hammer for 10 seconds
            Console.WriteLine("Running Hammer for 10 seconds");
            IHammerOptimization HammerOpt = TheSystem.Tools.OpenHammerOptimization();
            HammerOpt.RunAndWaitWithTimeout(10); // 10s of Hammer
            HammerOpt.Cancel();
            HammerOpt.WaitForCompletion();
            HammerOpt.Close();

C++

    // Hammer for 10 seconds
    IHammerOptimizationPtr HammerOpt = TheSystem->Tools->OpenHammerOptimization();
    baseTool = HammerOpt;
    baseTool->RunAndWaitWithTimeout(10);    
    baseTool->Cancel();
    baseTool->WaitForCompletion();
    baseTool->Close();

Matlab

    % Hammer for 10 seconds
    HammerOpt = TheSystem.Tools.OpenHammerOptimization();
    HammerOpt.RunAndWaitWithTimeout(10);    
    HammerOpt.Cancel();
    HammerOpt.WaitForCompletion();
    HammerOpt.Close();

Python

    # Hammer for 10 seconds
    # need to 'import time' at the top of the file to use the pause function
    print('Running Hammer Optimization')
    HammerOpt = TheSystem.Tools.OpenHammerOptimization()
    HammerOpt.RunAndWaitWithTimeout(10)    
    HammerOpt.Cancel()
    HammerOpt.WaitForCompletion()
    HammerOpt.Close()

Returns: true if the tool is asynchronous and is currently running; otherwise, false

Examples: CSharpStandalone_03_open_file_and_optimise.cs, CSharpStandalone_15_Seq_Optimization.cs, and CSharpStandalone_20_export_CAD_File.cs.

◆ Close()

bool ZOSAPI.Tools.ISystemTool.Close ( )

Closes this tool and frees up and associated resources.

Usage (see Example 15 for a full sample)

C#

            //change BFL & run quick focus                         
            Surface_Last.Thickness = 40.0;
            IQuickFocus QFocus = tools.OpenQuickFocus();
            QFocus.Criterion = QuickFocusCriterion.SpotSizeRadial;
            QFocus.UseCentroid = true;
            QFocus.RunAndWaitForCompletion();
            QFocus.Close();
            SampleFile = System.IO.Path.Combine(TheApplication.SamplesDir, @"API\CS\e15_Seq_Optimization\OptimizedFile2.zos");
            TheSystem.SaveAs(SampleFile);

C++

    // change BFL & run quick focus
    Surface_Last->Thickness = 40.0;
    IQuickFocusPtr QFocus = tools->OpenQuickFocus();
    QFocus->Criterion = QuickFocusCriterion::QuickFocusCriterion_SpotSizeRadial;
    QFocus->UseCentroid = true;
    ISystemToolPtr baseTool = QFocus;
    baseTool->RunAndWaitForCompletion();
    baseTool->Close();
    SampleFile = _bstr_t(TheApplication->SamplesDir) + "\\API\\CPP\\e15_Seq_Optimization\\OptimizedFile2.zos";
    TheSystem->SaveAs(SampleFile);

Matlab

    %change BFL & run quick focus                         
    Surface_Last.Thickness = 40.0;
    QFocus = tools.OpenQuickFocus();
    QFocus.Criterion = ZOSAPI.Tools.General.QuickFocusCriterion.SpotSizeRadial;
    QFocus.UseCentroid = true;
    QFocus.RunAndWaitForCompletion();
    QFocus.Close();
    SampleFile = System.String.Concat(TheApplication.SamplesDir, '\API\Matlab\e15_Seq_Optimization\OptimizedFile2.zos');
    TheSystem.SaveAs(SampleFile);

Python

    # change BFL & run quick focus
    Surface_Last.Thickness = 40.0
    QFocus = tools.OpenQuickFocus()
    QFocus.Criterion = ZOSAPI.Tools.General.QuickAdjustCriterion.SpotSizeRadial
    QFocus.UseCentroid = True
    QFocus.RunAndWaitForCompletion()
    QFocus.Close()
    SampleFile = TheApplication.SamplesDir + '\\API\\Python\\e15_Seq_Optimization\\OptimizedFile2.zos'
    TheSystem.SaveAs(SampleFile)

Returns: true if the tool is not currently running; otherwise, false.

Examples: CSharpStandalone_01_new_file_and_quickfocus.cs, CSharpStandalone_02_NSC_ray_trace.cs, CSharpStandalone_03_open_file_and_optimise.cs, CSharpStandalone_05_Read_ZRD_File.cs, CSharpStandalone_06_nsc_phase.cs, CSharpStandalone_07_TiltDecenterAndMFOperand.cs, CSharpStandalone_10_NSC_ZRD_filter_string.cs, CSharpStandalone_11_Basic_Seq.cs, CSharpStandalone_14_Seq_Tolerance.cs, CSharpStandalone_15_Seq_Optimization.cs, CSharpStandalone_17_NSC_BulkScatter.cs, CSharpStandalone_20_export_CAD_File.cs, CSharpStandalone_21_White_LED_Phosphor.cs, CSharpStandalone_24_nsc_detectors.cs, and CSharpStandalone_25_source_spectrum_diffraction_grating.cs.

◆ Run()

bool ZOSAPI.Tools.ISystemTool.Run ( )

Start the tool. Note that for synchronous tools (see IsAsynchronous), this call will block until completion. If it is asynchronous it will start running but return immediately.

Usage (see Example 20 for a full sample)

C#

            // Starting exporting
            // Run with a 3 minites timeout
            Console.Write("Starting exporting...");
            ToolExportCAD.Run();
            RunStatus runstatus = ToolExportCAD.WaitWithTimeout(3 * 60);
 
            // Report the status
            switch (runstatus)
            {
                case RunStatus.Completed:
                    Console.WriteLine("Completed!");
                    break;
                case RunStatus.FailedToStart:
                    Console.WriteLine("Failed To Start!");
                    break;
                case RunStatus.InvalidTimeout:
                    Console.WriteLine("Invalid Timeout!");
                    break;
                case RunStatus.TimedOut:
                    Console.WriteLine("Timed Out!");
                    break;
            }
            Console.WriteLine("Progress: " + ToolExportCAD.Progress.ToString("000") + "%");
 
            // If the exporting is not completed and can be cancelled, cancel the work
            if (runstatus != RunStatus.Completed & ToolExportCAD.CanCancel)
            {
                ToolExportCAD.Cancel();
            }
 
            // Close the tool
            ToolExportCAD.Close();

C++

    // Starting exporting
    // Run with a 3 minites timeout
    // Run() and WaitWithTimeout() is inherited from interface ISystemTool.
    // In C++ we need to cast before using these methods.
    cout << "Starting exporting..." << endl;
    ISystemToolPtr baseTool = ToolExportCAD;
    baseTool->Run();
    RunStatus runstatus = baseTool->WaitWithTimeout(3 * 60);
 
    // Report the status
    switch (runstatus)
    {
    case RunStatus_Completed:
        cout << "Completed!" << endl;
        break;
    case RunStatus_FailedToStart:
        cout << "Failed To Start!" << endl;
        break;
    case RunStatus_InvalidTimeout:
        cout << "Invalid Timeout!" << endl;
        break;
    case RunStatus_TimedOut:
        cout << "Timed Out!" << endl;
        break;
    }
    cout << "Progress: " << baseTool->Progress << endl;
 
    // If the exporting is not completed and can be cancelled, cancel the work
    if (runstatus != RunStatus_Completed & baseTool->CanCancel)
    {
        baseTool->Cancel();
    }
 
    // Close the tool
    baseTool->Close();

Matlab

    % Starting exporting
    % Run with a 3 minites timeout
    fprintf('Starting exporting...\n');
    ToolExportCAD.Run();
    [runstatus] = ToolExportCAD.WaitWithTimeout(3 * 60);
    
    % Report the status
    switch (runstatus)
        case ZOSAPI.Tools.RunStatus.Completed
            fprintf('Completed!\n');
        case ZOSAPI.Tools.RunStatus.FailedToStart
            fprintf('Failed To Start!\n');
        case ZOSAPI.Tools.RunStatus.InvalidTimeout
            cfprintf('Invalid Timeout!\n');
        case ZOSAPI.Tools.RunStatus.TimedOut
            fprintf('Timed Out!\n');
    end
    
    fprintf('Progress: %i\n', ToolExportCAD.Progress);
    
    % If the exporting is not completed and can be cancelled, cancel the work
    if (runstatus ~= ZOSAPI.Tools.RunStatus.Completed && ToolExportCAD.CanCancel)
        ToolExportCAD.Cancel();
    end
 
    % Close the tool
    ToolExportCAD.Close();

Python

    # Starting exporting
    # Run with a 3 minites timeout
    print('Starting exporting...')
    
    ToolExportCAD.Run()
    runstatus = ToolExportCAD.WaitWithTimeout(float(3 * 60))
 
    # Report the status
    if runstatus == ZOSAPI.Tools.RunStatus.Completed:
        print('Completed!')
    elif runstatus == ZOSAPI.Tools.RunStatus.FailedToStart:
        print('Failed To Start!')
    elif runstatus == ZOSAPI.Tools.RunStatus.InvalidTimeout:
        print('Invalid Timeout')
    else:
        print('Timed Out!')
 
    print('Progress: ', ToolExportCAD.Progress)
 
    # If the exporting is not completed and can be cancelled, cancel the work
    if (runstatus != ZOSAPI.Tools.RunStatus.Completed and ToolExportCAD.CanCancel):
        ToolExportCAD.Cancel()
 
    # Close the tool
    ToolExportCAD.Close()

Returns

true if the tool successfully started (and, for synchronous tools, completed); otherwise, false.

Note that if the tool is already running this will return false

.

Examples: CSharpStandalone_20_export_CAD_File.cs, and CSharpStandalone_21_White_LED_Phosphor.cs.

◆ RunAndWaitForCompletion()

bool ZOSAPI.Tools.ISystemTool.RunAndWaitForCompletion ( )

Sames as calling Run followed by WaitForCompletion.

Usage (see Example 15 for a full sample)

C#

            //change BFL & run quick focus                         
            Surface_Last.Thickness = 40.0;
            IQuickFocus QFocus = tools.OpenQuickFocus();
            QFocus.Criterion = QuickFocusCriterion.SpotSizeRadial;
            QFocus.UseCentroid = true;
            QFocus.RunAndWaitForCompletion();
            QFocus.Close();
            SampleFile = System.IO.Path.Combine(TheApplication.SamplesDir, @"API\CS\e15_Seq_Optimization\OptimizedFile2.zos");
            TheSystem.SaveAs(SampleFile);

C++

    // change BFL & run quick focus
    Surface_Last->Thickness = 40.0;
    IQuickFocusPtr QFocus = tools->OpenQuickFocus();
    QFocus->Criterion = QuickFocusCriterion::QuickFocusCriterion_SpotSizeRadial;
    QFocus->UseCentroid = true;
    ISystemToolPtr baseTool = QFocus;
    baseTool->RunAndWaitForCompletion();
    baseTool->Close();
    SampleFile = _bstr_t(TheApplication->SamplesDir) + "\\API\\CPP\\e15_Seq_Optimization\\OptimizedFile2.zos";
    TheSystem->SaveAs(SampleFile);

Matlab

    %change BFL & run quick focus                         
    Surface_Last.Thickness = 40.0;
    QFocus = tools.OpenQuickFocus();
    QFocus.Criterion = ZOSAPI.Tools.General.QuickFocusCriterion.SpotSizeRadial;
    QFocus.UseCentroid = true;
    QFocus.RunAndWaitForCompletion();
    QFocus.Close();
    SampleFile = System.String.Concat(TheApplication.SamplesDir, '\API\Matlab\e15_Seq_Optimization\OptimizedFile2.zos');
    TheSystem.SaveAs(SampleFile);

Python

    # change BFL & run quick focus
    Surface_Last.Thickness = 40.0
    QFocus = tools.OpenQuickFocus()
    QFocus.Criterion = ZOSAPI.Tools.General.QuickAdjustCriterion.SpotSizeRadial
    QFocus.UseCentroid = True
    QFocus.RunAndWaitForCompletion()
    QFocus.Close()
    SampleFile = TheApplication.SamplesDir + '\\API\\Python\\e15_Seq_Optimization\\OptimizedFile2.zos'
    TheSystem.SaveAs(SampleFile)

Returns: true if the call to Run succeeded, IsAsynchronous is true, and IsFiniteDuration is false; otherwise, false

Examples: CSharpStandalone_01_new_file_and_quickfocus.cs, CSharpStandalone_02_NSC_ray_trace.cs, CSharpStandalone_03_open_file_and_optimise.cs, CSharpStandalone_05_Read_ZRD_File.cs, CSharpStandalone_06_nsc_phase.cs, CSharpStandalone_07_TiltDecenterAndMFOperand.cs, CSharpStandalone_10_NSC_ZRD_filter_string.cs, CSharpStandalone_11_Basic_Seq.cs, CSharpStandalone_14_Seq_Tolerance.cs, CSharpStandalone_15_Seq_Optimization.cs, CSharpStandalone_17_NSC_BulkScatter.cs, CSharpStandalone_18_SetMulticonfiguration.cs, CSharpStandalone_22_seq_spot_diagram.cs, CSharpStandalone_23_ray_fan_native_manual_comparison.cs, CSharpStandalone_24_nsc_detectors.cs, and CSharpStandalone_25_source_spectrum_diffraction_grating.cs.

◆ RunAndWaitWithTimeout()

RunStatus ZOSAPI.Tools.ISystemTool.RunAndWaitWithTimeout ( double timeOutSeconds )

Starts the tool running, and waits for it to complete with the specified timeout value. Note that if the timeout is exceeded this method will return, however the tool will continue to run.

Parameters

timeOutSeconds The time out value (seconds). Note that this value must be greater than zero, else a RunStatus.InvalidTimeout value will be returned.

Returns: A RunStatus value indicating the tool state.///

Examples: CSharpStandalone_03_open_file_and_optimise.cs, and CSharpStandalone_15_Seq_Optimization.cs.

◆ WaitForCompletion()

bool ZOSAPI.Tools.ISystemTool.WaitForCompletion ( )

Waits for the asynchronous tool to complete.

Returns: true if the tool is running, it is asynchronous, and it has a finite run duration; otherwise, false.

Examples: CSharpStandalone_03_open_file_and_optimise.cs, and CSharpStandalone_15_Seq_Optimization.cs.

◆ WaitWithTimeout()

RunStatus ZOSAPI.Tools.ISystemTool.WaitWithTimeout ( double timeOutSeconds )

Waits for the currently running tool to complete, with a specified time out value. Note that if the timeout is exceeded this method will return, however the tool will continue to run. Also note that this method will not start the tool running if it is not already.

Parameters

timeOutSeconds The time out value (seconds). Note that this value must be greater than zero, else a RunStatus.InvalidTimeout value will be returned.

Returns: A RunStatus value indicating the tool state.///

Examples: CSharpStandalone_20_export_CAD_File.cs.

Property Documentation

◆ CanCancel

bool ZOSAPI.Tools.ISystemTool.CanCancel

get

Gets a value indicating whether the tool can be cancelled.

true if this tool is asynchronous and can be cancelled; otherwise, false.

Examples: CSharpStandalone_20_export_CAD_File.cs.

◆ ErrorMessage

string ZOSAPI.Tools.ISystemTool.ErrorMessage

get

If Succeeded is false, get the error messages; otherwise, null.

The error message.

Examples: CSharpStandalone_05_Read_ZRD_File.cs.

◆ IsAsynchronous

bool ZOSAPI.Tools.ISystemTool.IsAsynchronous

get

Gets a value indicating whether the tool runs asynchronously (i.e. on a thread).

true if this the tool is asynchronous; otherwise, false.

◆ IsFiniteDuration

bool ZOSAPI.Tools.ISystemTool.IsFiniteDuration

get

Gets a value indicating whether this tool will complete on its own.

true if the tool is synchronous, or if it is asynchronous and will terminate on its own; otherwise, false.

◆ IsRunning

bool ZOSAPI.Tools.ISystemTool.IsRunning

get

Gets a value indicating whether the tool is currently running asynchronously.

true if the tool is currently running; otherwise, false.

◆ IsValid

bool ZOSAPI.Tools.ISystemTool.IsValid

get

Gets a value indicating whether the input settings are valid.

true if the settings are valid; otherwise, false.

◆ Progress

int ZOSAPI.Tools.ISystemTool.Progress

get

Gets the progress of the current tool, if supported.

The progress (0-100)

Examples: CSharpStandalone_20_export_CAD_File.cs, and CSharpStandalone_21_White_LED_Phosphor.cs.

◆ Status

string ZOSAPI.Tools.ISystemTool.Status

get

Gets the status of the current tool, if supporoted.

The status message;

◆ Succeeded

bool ZOSAPI.Tools.ISystemTool.Succeeded

get

Gets a value indicating whether the tool execution succeeded.

true if the last execution of the tool succeeded; otherwise, false.

Examples: CSharpStandalone_05_Read_ZRD_File.cs.

ZOS-API interface 2025 R1

ZOSAPI.Tools.ISystemTool Interface Reference

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ Cancel()

◆ Close()

◆ Run()

◆ RunAndWaitForCompletion()

◆ RunAndWaitWithTimeout()

◆ WaitForCompletion()

◆ WaitWithTimeout()

Property Documentation

◆ CanCancel

◆ ErrorMessage

◆ IsAsynchronous

◆ IsFiniteDuration

◆ IsRunning

◆ IsValid

◆ Progress

◆ Status

◆ Succeeded

Connect with Ansys