(Hide table-of-contents)

Execute is part of the CategoryAplTree project.


Execute provides two methods:

Use Application in order to run a program or a batch file when you are not in need for its output. A typical example is firing up another instance of Dyalog APL. Use Process if you need the output of a certain program. A typical example would be the SubVersion "svn list" command.

Naturally Process waits for the program to quit. Application doesn't wait by default but you can change that default behaviour. If you do you will get the exit code of that application, if there is any. A return code can be returned by a Dyalog app with

      ⎕OFF 123

and in a batch file with

exit 123


Imagine you want run a foo.exe which returns a 0 in case of success and a positive integer in case of an error.

Now in order to kick off an instance of foo.exe one could simply execute:

      ⎕CMD 'foo.exe'

So why should someone bother to use Execute instead? Well, there are a couple of good reasons:

The class Execute is designed to get you around these obstacles.

Examples: the "Application" method

All examples assume that you have a variable path in your workspace which points to the Dyalog EXE. A typical path would be:

"C:\Program Files (x86)\Dyalog\Dyalog APL 12.1 Unicode\dyalog.exe"

Start a program and wait until it exits

This can be achieved with the default settings of the parameters you might specify:

       res←Execute.Application path

This starts another Dyalog APL. The method Execute.Application waits until the started Dyalog APL exits.

      ⎕←Display'rc' 'processInfo' 'result' 'more',[⎕IO+0.1]res
↓ ┌→─┐                                │
│ │rc│          0                     │
│ └──┘                                │
│ ┌→──────────┐ ┌→──────────────────┐ │
│ │processInfo│ │1228 1592 3292 6728│ │
│ └───────────┘ └~──────────────────┘ │
│ ┌→─────┐                            │
│ │result│      245                   │
│ └──────┘                            │
│ ┌→───┐        ┌⊖┐                   │
│ │more│        │ │                   │
│ └────┘        └─┘                   │

As you can see the "result" returned by the called application is 245. This is achieved by executing

      ⎕OFF 245

in that application.

Start another program but don't wait for it

In order to achieve that we need to change one of the defaults. First create a namespace with all parameters and their default settings:


This creates a namespace with all parameters you may change. You can list the parameters available by calling the namespace's List method:

 timeoutAfter  0
 hidden        0   
 wait          1   

Note that timeoutAfter←0 means no timeout at all while any positive integer is treated as number of seconds.

Now make your changes:


Now run the application:

    cs Execute.Application path,'  dlgtest.dws'

This starts Dyalog which then in turn loads the workspace DLGTEST. Although the application writes to the session you won't see the session because of hidden being 1. Note that this means that if the app crashes for any reason the user has no other means to finish the application than killing the process in the task manager.

Examples: the "Process" method

The Process method is designed to return whatever the called program is going to write to stdout. For that reason Process always waits until "program" exits. The application returns three items:

  1. An indicator whether "program" could be started at all. 0 is okay while 1 means failure.
  2. Everything that was written to stdout by "program". This is either a simple string of a vector of strings.
  3. The exit code of the pogram called. If there is no exit code this is -1.

Simple right argument

The following example would work in case the following preconditions are full-filled:

      cmd←'svn list svn://',path
      ↑(1+⎕io)⊃#.Execute.Application cmd

Nested right argument

Rather then specifying a simple right argument you can also pass a vector of strings. The first one is used in order to identify the program to be executed while the other items are used as input.

The following example works although it's by no means suggested to do this: The WinFile class offers a much better way so solve this. For example, if there are any non-ANSII-characters used in a file- or directory name, than you won't see them: they will show up as question marks. However, to demonstrate the usage of a vector of strings the example is fine.

Our goal is to start a command.com instance, execute the dir command and exit the command.com instance while returning an exit code 9:

      cmd←'cmd' 'dir' 'exit 9'
      ↑(1+⎕io)⊃#.Execute.Application cmd
Microsoft Windows [Version 6.1.7600]                           
Copyright (c) 2009 Microsoft Corporation.  All rights reserved.


Note that you cannot specify input for a Dyalog session this way.


Many thanks to Peter-Michael Hager without whom this class wouldn't exist.

Project Page

For bug reports, future enhancements and a full version history see Execute/ProjectPage

Version Information

Original author:






APLTree downloads

Using an APLTree member

  1. If you just want to consume (use) an APLTree member then you have several choices:
    • Note that accessing it via ftp allows you to download older versions as well while the dedicated download page offers just the most current version.


If you want to contribute to an APLTree project see HowToContributeToTheAPLTreeProject for details.

Get the full project

If for some reason you need access to, say, the test cases then you need to get more then just the script (or application) itself.

HowToContributeToTheAPLTreeProject explains how to get a project onto your local machine. Just ignore any additional steps.

Create a new APLTree sub project

In order to create a new APLTree project you need some advice. Ask KaiJaeger for help: mailto:kai@aplteam.com


Execute (last edited 2014-09-19 09:04:00 by KaiJaeger)