---
title: "Program: list, start, stop and read the execution"
description: "List, select, start, pause, hold and stop robot programs, read their execution and call stack, and read and write program positions with robot.Program. Brand support table, C# and Python examples."
---

# Program: list, start, stop and read the execution

`robot.Program` lists, selects, starts, pauses and stops the programs of a robot controller, reads their execution state, and reads and writes the positions stored in a program. The same calls work on Fanuc, Yaskawa, Universal Robots, ABB and Stäubli controllers, for the methods that the brand supports.

## Prerequisites

- A connected `RobotController`. See [Connect to your robot](/robotics/documentation/connect).
- The license of the brand of the controller, or the 30 day trial. See [Licensing](/robotics/documentation/license).
- For `Start` and `StartAtLine`: the controller can need its automatic or remote mode, and the servo power. See [State](/robotics/documentation/state).
- A program is named with its native name, as the controller names it.

## Brand support

Each cell gives the protocol that the method uses on this brand, in the default order. The page [Routing](/robotics/documentation/routing) explains how the library chooses it. The table is generated from the route data of the library. (manual) marks a route that you enable yourself. "n of m" is the number of methods of the service that have a route on this brand. The rows `Program.Position.*` are the methods of `robot.Program.Position`.

Routes of each method in the default order. The first route is used, the next ones are fallbacks. (manual) marks a route that you enable yourself.

| Method | Fanuc | Yaskawa | Universal Robots | ABB | Stäubli |
| --- | --- | --- | --- | --- | --- |
| Program.List | CGTP (Cgtp), FTP | High Speed Ethernet Server, Ethernet Server, FTP | SFTP | Robot Web Services | SOAP, Files |
| Program.Select | CGTP (Cgtp) | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Start | CGTP (Cgtp), CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Pause | CGTP (Cgtp), CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Resume | CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Stop | CGTP (Cgtp), CGTP (CgtpKcl), Telnet | Not available | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.ReadExecution | SNPX, CGTP (CgtpKcl), Telnet, FTP | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Hold | CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Not available | Not available | Not available |
| Program.SetCycleMode | Not available | High Speed Ethernet Server, Ethernet Server | Not available | Robot Web Services | Not available |
| Program.SelectAtLine | CGTP (Cgtp) | High Speed Ethernet Server, Ethernet Server | Not available | Robot Web Services | Not available |
| Program.StartAtLine | CGTP (Cgtp) | High Speed Ethernet Server, Ethernet Server | Not available | Robot Web Services | Not available |
| Program.StopTask | CGTP (Cgtp), CGTP (CgtpKcl), Telnet | Not available | Not available | Not available | SOAP |
| Program.Position.Read | FTP, CGTP (Cgtp) | FTP, High Speed Ethernet Server | Not available | Robot Web Services | Not available |
| Program.Position.Write | CGTP (Cgtp) | Not available | Not available | Robot Web Services | Not available |
| Program.Position.SetToCurrent | CGTP (Cgtp) | Not available | Not available | Robot Web Services | Not available |
| Program | **14 of 15** | **11 of 15** | **7 of 15** | **13 of 15** | **8 of 15** |

A brand that has no route for a method throws `FeatureNotSupportedException` (see [Errors](/robotics/documentation/errors)). Ask `robot.Program.IsAvailable(ProgramFeature.StartAtLine)` before the call.

## Example

### List, select and start a program

`Select` selects a program, so that `Start` without a name starts it. In Python, an empty name (`start("")`) starts the selected program. `Start("MAIN")` starts a program by its name. `Pause` keeps the program at its line and `Resume` continues it. `Stop` aborts the running program.

**C# : ProgramList**
```csharp
using UnderAutomation.Robotics.Controllers;

public class ProgramList
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        foreach (RobotProgramInfo program in robot.Program.List())
            Console.WriteLine($"{program.Name} {program.Comment}");
        /**/

        robot.Disconnect();
    }
}
```

**Python : ProgramList**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
for program in robot.program.list():
    print(f"{program.name} {program.comment}")
##

robot.disconnect()
```

**C# : ProgramStart**
```csharp
using UnderAutomation.Robotics.Controllers;

public class ProgramStart
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // Native name of the program, as the pendant shows it
        robot.Program.Select("MAIN");
        robot.Program.Start();

        // Pause keeps the program at its line, Resume continues it
        robot.Program.Pause();
        robot.Program.Resume();

        robot.Program.Stop();
        /**/

        robot.Disconnect();
    }
}
```

**Python : ProgramStart**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# Native name of the program, as the pendant shows it
robot.program.select("MAIN")

# An empty name starts the selected program
robot.program.start("")

# Pause keeps the program at its line, resume continues it
robot.program.pause()
robot.program.resume()

robot.program.stop()
##

robot.disconnect()
```

### Start from a line, set the cycle mode, hold a program

`StartAtLine` starts a program from a line, counted from 1. `SetCycleMode` sets how far a program runs after a start: one step, one cycle or continuously. `Hold` decelerates the robot and stops it on its path. On a brand where a hold and a pause are the same function of the controller, both methods send it. `StopTask` aborts one task and leaves the others running.

**C# : ProgramStartAtLine**
```csharp
using UnderAutomation.Robotics.Controllers;

public class ProgramStartAtLine
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // Not supported by every brand: ask first
        if (robot.Program.IsAvailable(ProgramFeature.StartAtLine))
        {
            robot.Program.StartAtLine("MAIN", 10);
        }

        robot.Program.SetCycleMode(CycleMode.OneCycle);
        robot.Program.Hold();
        robot.Program.StopTask("MAIN");
        /**/

        robot.Disconnect();
    }
}
```

**Python : ProgramStartAtLine**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters
from underautomation.robotics.controllers.cycle_mode import CycleMode
from underautomation.robotics.controllers.program_feature import ProgramFeature

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# Not supported by every brand: ask first
if robot.program.is_available(ProgramFeature.StartAtLine):
    robot.program.start_at_line("MAIN", 10)

robot.program.set_cycle_mode(CycleMode.OneCycle)
robot.program.hold()
robot.program.stop_task("MAIN")
##

robot.disconnect()
```

### Read the execution state

`ReadExecution` returns one `ProgramExecution` per task. `Stack` is the call stack, the current program first. It is empty when the route does not read it.

**C# : ProgramReadExecution**
```csharp
using UnderAutomation.Robotics.Controllers;

public class ProgramReadExecution
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        foreach (ProgramExecution execution in robot.Program.ReadExecution())
        {
            Console.WriteLine($"{execution.Task}: {execution.Program}, line {execution.Line}, {execution.Status}");

            foreach (ProgramFrame frame in execution.Stack)
                Console.WriteLine($"  called from {frame.Program}, line {frame.Line}");
        }
        /**/

        robot.Disconnect();
    }
}
```

**Python : ProgramReadExecution**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
for execution in robot.program.read_execution():
    print(f"{execution.task}: {execution.program}, line {execution.line}, {execution.status.name}")

    for frame in execution.stack:
        print(f"  called from {frame.program}, line {frame.line}")
##

robot.disconnect()
```

### Read and write the positions of a program

**C# : ProgramPositionRead**
```csharp
using UnderAutomation.Robotics.Controllers;

public class ProgramPositionRead
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        foreach (ProgramPosition position in robot.Program.Position.Read("MAIN"))
            Console.WriteLine($"{position.Name}: X {position.Position.Pose.X}, Y {position.Position.Pose.Y}, Z {position.Position.Pose.Z}");
        /**/

        robot.Disconnect();
    }
}
```

**Python : ProgramPositionRead**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
for position in robot.program.position.read("MAIN"):
    print(f"{position.name}: X {position.position.pose.x}, Y {position.position.pose.y}, Z {position.position.pose.z}")
##

robot.disconnect()
```

`SetToCurrent` writes the current position of the robot in a position of the program and returns it. `Write` writes a position that you computed. A stored Cartesian position does not depend on the state of the robot at the time of the write: a brand that stores the frame, the tool and the configuration refuses a Cartesian value that does not give them.

**C# : ProgramPositionWrite**
```csharp
using UnderAutomation.Robotics.Controllers;

public class ProgramPositionWrite
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // Teach a position at the current place of the robot
        RobotPosition taught = robot.Program.Position.SetToCurrent("MAIN", "P[1]");

        // Or write a position that you computed
        RobotPosition target = robot.Motion.ReadPose();
        target.Pose.Z += 50;
        robot.Program.Position.Write("MAIN", "P[2]", target);
        /**/

        robot.Disconnect();
    }
}
```

**Python : ProgramPositionWrite**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# Teach a position at the current place of the robot
taught = robot.program.position.set_to_current("MAIN", "P[1]")

# Or write a position that you computed
target = robot.motion.read_pose()
target.pose.z += 50
robot.program.position.write("MAIN", "P[2]", target)
##

robot.disconnect()
```

## Reference

In Python, the names are in snake_case: `robot.program.list()`, `robot.program.start_at_line(...)`, `robot.program.read_execution()`, `robot.program.position.read(...)`. The enum members keep their names.

### Methods of IProgramService

**Members of Controllers.IProgramService**
```csharp
public interface IProgramService {
    // Holds the running programs: the robot decelerates and stops on its path, the program stays at its line, <xref href="UnderAutomation.Robotics.Controllers.IProgramService.Resume" data-throw-if-not-resolved="false"></xref> continues it.
    // On a brand where the hold and the pause are the same function of the controller, both methods send it.
    // A refusal that the controller answers throws <xref href="UnderAutomation.Robotics.Controllers.ControllerRefusedException" data-throw-if-not-resolved="false"></xref>. Some routes get no answer from the controller
    // (the route list of the brand says which): there a refusal is not seen, read <xref href="UnderAutomation.Robotics.Controllers.IProgramService.ReadExecution" data-throw-if-not-resolved="false"></xref> to check the result.
    void Hold()

    // Returns true when the method can be called on the connected controller.
    // The answer depends on the brand, on the routing settings and on the protocols that answered at the connection, not on the state of the controller.
    bool IsAvailable(ProgramFeature feature)

    // Lists the programs of the controller
    RobotProgramInfo[] List()

    // Pauses the running program. <xref href="UnderAutomation.Robotics.Controllers.IProgramService.Resume" data-throw-if-not-resolved="false"></xref> continues it. On a brand where a hold is another function of the controller, <xref href="UnderAutomation.Robotics.Controllers.IProgramService.Hold" data-throw-if-not-resolved="false"></xref> sends it.
    void Pause()

    // Positions stored in the programs
    IProgramPositionService Position { get; }

    // Reads the execution state of each task of the controller: program, line, status and call stack
    // (<xref href="UnderAutomation.Robotics.Controllers.ProgramExecution.Stack" data-throw-if-not-resolved="false"></xref>, empty when the route does not read it)
    ProgramExecution[] ReadExecution()

    // Resumes the program paused by <xref href="UnderAutomation.Robotics.Controllers.IProgramService.Pause" data-throw-if-not-resolved="false"></xref> or <xref href="UnderAutomation.Robotics.Controllers.IProgramService.Hold" data-throw-if-not-resolved="false"></xref>. A program stopped on a breakpoint or in step mode
    // continues with <xref href="UnderAutomation.Robotics.Controllers.IDebugService.Continue" data-throw-if-not-resolved="false"></xref>.
    void Resume()

    // Selects a program, so that <xref href="UnderAutomation.Robotics.Controllers.IProgramService.Start(System.String)" data-throw-if-not-resolved="false"></xref> without name starts it
    void Select(string name)

    // Selects a program with its cursor at a line, so that <xref href="UnderAutomation.Robotics.Controllers.IProgramService.Start(System.String)" data-throw-if-not-resolved="false"></xref> without name starts it from this line
    void SelectAtLine(string name, int line)

    // Sets the cycle mode of the controller: step, one cycle or continuous. The mode applies to the next start or resume, for every program.
    // A brand can refuse a mode that its controller does not have with an <xref href="System.ArgumentException" data-throw-if-not-resolved="false"></xref>.
    // For a debug session, use <xref href="UnderAutomation.Robotics.Controllers.IDebugService.SetStepMode(System.Boolean)" data-throw-if-not-resolved="false"></xref> and <xref href="UnderAutomation.Robotics.Controllers.IDebugService.Continue" data-throw-if-not-resolved="false"></xref>: they also work on the brands where the step mode is not a cycle mode.
    void SetCycleMode(CycleMode mode)

    // Starts a program. The controller can need its automatic or remote mode and the servo power.
    void Start(string name = "")

    // Starts a program from a line. The controller can need its automatic or remote mode and the servo power.
    // A brand that selects the program first, then starts it, leaves the program selected at this line when the start is refused.
    void StartAtLine(string name, int line)

    // Stops (aborts) the running program
    void Stop()

    // Stops (aborts) one task. The other tasks keep running.
    void StopTask(string task)
}
```

`Hold` can get no answer from the controller on some routes. A refusal is then not seen: read `ReadExecution` to check the result.

### Methods of IProgramPositionService

**Members of Controllers.IProgramPositionService**
```csharp
public interface IProgramPositionService {
    // Returns true when the method can be called on the connected controller.
    // The answer depends on the brand, on the routing settings and on the protocols that answered at the connection, not on the state of the controller.
    bool IsAvailable(ProgramPositionFeature feature)

    // Reads the positions stored in a program
    ProgramPosition[] Read(string program)

    // Writes the current position of the robot in a position stored in a program, and returns the position written
    RobotPosition SetToCurrent(string program, string name)

    // Writes a position stored in a program, for the motion group of the value (<xref href="UnderAutomation.Robotics.Controllers.RobotPosition.Group" data-throw-if-not-resolved="false"></xref>).
    // A joint value writes its joints, a Cartesian value writes its pose with the external axes of the pose (<xref href="UnderAutomation.Robotics.Geometry.CartesianPose.ExternalAxes" data-throw-if-not-resolved="false"></xref>).
    // A stored Cartesian position does not depend on the state of the robot at the time of the write: a brand whose stored positions keep the number of the frame,
    // the number of the tool and the configuration refuses a Cartesian value with a frame or a tool of -1, or with a posture <code>Same</code> and no configuration object of the brand.
    void Write(string program, string name, RobotPosition position)
}
```

### Result types

**Members of Controllers.RobotProgramInfo**
```csharp
public sealed class RobotProgramInfo {
    // Creates a program description with the default value of each property
    public RobotProgramInfo()

    // Comment of the program. Empty when the program has none.
    public string Comment { get; set; }

    // Name of the program, as used by the other methods of the program service
    public string Name { get; set; }

    // Object of the brand SDK this program comes from. Null when there is none.
    public object Native { get; set; }

    // Task that holds the program, on controllers that load programs per task. Empty otherwise.
    public string Task { get; set; }

    public override string ToString()
}
```

**Members of Controllers.ProgramExecution**
```csharp
public sealed class ProgramExecution {
    // Creates an execution state with the default value of each property
    public ProgramExecution()

    // Line executed in the program, from 1. 0 when the controller does not give it.
    public int Line { get; set; }

    // Object of the brand SDK this state comes from. Null when there is none.
    public object Native { get; set; }

    // Name of the program executed by the task. Empty when no program is selected.
    public string Program { get; set; }

    // Call stack of the task, current frame first: the first frame is the program and the line executed,
    // the next frames are the calling programs, up to the program the task started with.
    // Empty when the route does not read the call stack. Never null.
    public ProgramFrame[] Stack { get; set; }

    // Execution status
    public ExecutionStatus Status { get; set; }

    // Name of the task. Empty when the controller has only one task without name.
    public string Task { get; set; }

    public override string ToString()
}
```

**Members of Controllers.ExecutionStatus**
```csharp
public enum ExecutionStatus {
    // The program is paused (held). It can be resumed.
    Paused = 2

    // The program is running
    Running = 1

    // No program is running
    Stopped = 3

    // The controller does not give the status
    Unknown = 0
}
```

**Members of Controllers.ProgramFrame**
```csharp
public sealed class ProgramFrame {
    // Creates a frame of a call stack with the default value of each property
    public ProgramFrame()

    // Line executed in the program, from 1. 0 when the controller does not give it,
    // for example for a calling program on some controllers.
    public int Line { get; set; }

    // Name of the program of this frame, written like <xref href="UnderAutomation.Robotics.Controllers.ProgramExecution.Program" data-throw-if-not-resolved="false"></xref>
    public string Program { get; set; }

    public override string ToString()
}
```

**Members of Controllers.ProgramPosition**
```csharp
public sealed class ProgramPosition {
    // Creates a program position with the default value of each property
    public ProgramPosition()

    // Comment of the position. Empty when it has none.
    public string Comment { get; set; }

    // Native name of the position in the program, as the program writes it. It is the name given to the other methods of the program position service.
    public string Name { get; set; }

    // Object of the brand SDK this position comes from. Null when there is none.
    public object Native { get; set; }

    // The position. Setting null gives a position at the origin.
    public RobotPosition Position { get; set; }

    public override string ToString()
}
```

**Members of Controllers.CycleMode**
```csharp
public enum CycleMode {
    // The program runs again from its start each time it reaches its end
    Continuous = 3

    // The program runs once to its end, then stops
    OneCycle = 2

    // The program stops after each instruction. The next start or resume runs the next instruction.
    Step = 1

    // The controller does not give the mode. Refused by <xref href="UnderAutomation.Robotics.Controllers.IProgramService.SetCycleMode(UnderAutomation.Robotics.Controllers.CycleMode)" data-throw-if-not-resolved="false"></xref>.
    Unknown = 0
}
```

### Errors

The page [Errors](/robotics/documentation/errors) explains each exception and how to avoid it.

- `FeatureNotSupportedException`: the brand has no route for the method.
- `RouteUnavailableException`: the method has routes, but none of them can be used, for example because the protocol did not answer at the connection.
- `ControllerRefusedException`: the controller received the command and refused it.
- `RobotControllerException`: the route failed. Its inner exception is the exception of the brand SDK.
- `ArgumentException`: an invalid argument, for example a cycle mode that the controller does not have.

`IsAvailable` only throws `ArgumentOutOfRangeException`, for a value that is not in the enum.

## What to read next

- [Start, stop and select a robot program](/robotics/documentation/how-to-run-program): the same start on each brand, with the program names and the modes of each brand.
- [Debug](/robotics/documentation/debug): breakpoints and step mode.
- [State](/robotics/documentation/state): operating mode and servo power.
- [Alarm](/robotics/documentation/alarm): read and reset the alarms that stop a program.