REBOL 3 Functions: call

Note this special requirement:

Security

In order to use call, you must have secure call enabled.

Description

The call function interfaces to the operating system's command shell to execute programs, shell commands, and redirect command input and output.

call is normally blocked by the security level specified with the secure function. To use it, you must change your secure settings or run the script with reduced security (at your own risk):

secure call

The call function accepts one argument, which can be a string or a block specifying a shell command and its arguments. The following example shows a string as the call argument.

call "cp source.txt dest.txt"

Use a block argument with call when you want to include REBOL values in the call to a shell command, as shown in the following example:

source: %source.txt
dest: %dest.txt
call reduce ["cp" source dest]

The call function translates the file names in a block to the notation used by the shell. For example:

[dir %/c/windows]

will convert the file name to windows shell syntax before doing it.

When shell commands are called, they normally run as a separate process in parallel with REBOL. They are asynchronous to REBOL. However, there are times when you want to wait for a shell command to finish, such as when you are executing multiple shell commands.

In addition, every shell command has a return code, which normally indicates the success or failure of the command. Typically, a shell command returns zero when it is successful and a non-zero value when it is unsuccessful.

The /wait refinement causes the call function to wait for a command's return code and return it to the REBOL program. You can then use the return code to verify that a command executed successfully, as shown in the following example:

if zero? call/wait "dir" [
    print "worked"
]

In the above example, call successfully executes the Windows dir command, which is indicated by the zero return value. However, in the next example, call is unsuccessful at executing the xcopy command, which is indicated by the return value other than zero.

if not zero? code: call/wait "xcopy" [
    print ["failed:" code]
]

In Windows and Unix (Linux), input to a shell command can be redirected from a file, URL, string, or port. By default, a shell command's output and errors are ignored by REBOL. However, shell command output and errors can be redirected to a file, URL, port, string, or the REBOL console.

instr: "data"
outstr: copy ""
errstr: copy ""
call/input/output/error "sort" instr outstr errstr
print [outstr errstr]

See the REBOL Command Shell Interface documentation for more details.

Editor note: Proper link to the REBOL Command Shell Interface?