⎕HOST Command to Host

The ⎕HOST system function allows you to issue a command directly to the host operating-system environment and display or capture the result, without leaving the APL workspace. This system function is highly implementation-specific and some operating system commands may not be allowed.

⎕HOST takes as its right argument the command to be executed. It returns the output (if any) from the command as a character vector, possibly with embedded newline characters. You can also optionally specify a left argument which is the maximum time (in seconds) to wait before returning control to APL. This is useful to prevent your APL program being blocked if, for example, the program called encounters an error which causes it to wait for input from the command-line. If the optional left argument is omitted, a default timeout of 20 seconds is used.

If the right argument to ⎕HOST is an empty vector, it returns a character vector with the operating system name: 'LINUX' 'AIX' 'WINDOWS' or 'MACOS'

For example, under Linux:

            ⎕HOST ''
      LINUX
            SERVER←⎕HOST 'hostname'
            SERVER
      penguin
           10 ⎕HOST 'telnet rs6000'

Note that, under Windows, many common commands are 'built-in' to the command-line shell, rather than being separate executable programs. Under Windows NT, 2000, XP and Vista, you can run these using the 'CMD' program with the '/C' option. (Under Windows 95, 98 and ME, use 'COMMAND.COM /C'). For example:

            ⎕HOST 'CMD /C dir'
     Volume in drive C has no label.
     Volume Serial Number is 07D0-0B11

          Directory of C:\aplx\ws

     20/06/2001  19:13       [DIR]          .
     20/06/2001  19:13       [DIR]          ..
     05/09/2001  16:43               17,792 JIM.aws
     05/09/2001  17:06                  574 EXPLORE.atf
     30/07/2001  19:49               17,828 QNA.aws
               3 File(s)         39,313 bytes
               2 Dir(s)  14,797,176,832 bytes free

Under MacOS 8 and 9, because there is no command-line interface at the operating system, ⎕HOST is not implemented except to report the OS name. Under MacOS X, ⎕HOST runs the command under the BSD Unix-style shell.

Special considerations for Client-Server implementations of APLX

In Client-Server implementations of APLX, the front-end which implements the user-interface (the "Client") runs on one machine, and the APLX interpreter itself (the "Server") can run on a different machine. The two parts of the application communicate via a TCP/IP network. Typically, the Client will be the APLX front-end built as a 32-bit Windows application running on a desktop PC, and the Server will be a 64-bit APLX64 interpreter running on a 64-bit Linux or Windows server.

In such systems, ⎕HOST allows you to specify whether the command should be executed on the Client or the Server machine. You do this by preceding the ⎕HOST right argument with either an Up Arrow ↑ to indicate that the command should be executed on the Client, or a Down Arrow ↓ to indicate that it should run on the Server. If you do not specify, the default is that the call should take place on the Client.

In this example, the Client is running under Windows, and the Server under Linux x86_64:

      ⎕HOST '↑cmd /c vol c:'            ⍝ Execute on Windows Client machine
 Volume in drive C has no label.
 Volume Serial Number is 07D0-0B11

      ⎕HOST '↓uname -nsp'               ⍝ Execute on Linux Server machine
Linux Server23 x86_64