Executing a child task¶

exec[u]

Execute a child task

SYNTAX

exec[u] command [stdin = #channel] [stdout = #channel] [on server_name]

Child task termination code
The execu command
Wine programs

Executes command as an operating system command line. When the child task terminates, control returns to the statement following the exec.

Note the following different forms of the exec command line:

1	exec[u] “progname args” Creates a shell and executes the program as a shell command. A shell is needed on UNIX to expand wildcard arguments and to handle I/O redirection. On Windows, a shell is needed to execute an MS-DOS program or a Windows console program (a program that runs from the operating system command line in character mode). It is not needed to execute a Windows program, and this form of the command merely creates an unnecessary command shell.
2	exec[u] “progname args `&`” As form 1, except that parent and child run concurrently.
3	exec[u] “`-`progname args” Creates a new program as a direct child process. The parent program waits for the child program to exit before continuing or accepting events. The exit code of the process is returned in sys.Status. Note that when this form is used, Windows will create a shell for an MS-DOS or console program even though it was not specified. However, it is recommended that if a shell is needed it should always be specified (by omitting the leading hyphen), in order to ensure portability to other platforms.
4	exec[u] “`-`progname args `&`” Creates a new program as a direct child process and does not wait for the child program to exit, so that both parent and child run concurrently.
5	exec[u] “`-`progname args `&&`” Creates a new Windows program and runs it without an initial delay. When Sculptor starts a child process, it normally calls a Windows function that waits for the child process to finish initialising. The parent program does not continue until either the child process is “waiting for user input with no input pending”, or a timeout period of 30 seconds has elapsed. This allows the child process time to start up and gain focus. An unnecessary delay is caused if the child process does not normally interact with the user, or has substantial work to do before such interaction. Adding “&&” to the command line avoids this delay.
6	exec[u] “`-–`progname args” This form and the following one are meaningful only on Microsoft Windows. On Unix both work the same way as a single “-”. On Windows, they can be used to execute a console program that does not use I/O redirection. They avoid the flashing effect caused by the appearance of a Windows console. This form executes the program without a console window. The program cannot create a console later. This form cannot be used on Windows 98 or ME.
7	exec “`-+`progname args” Identical to the previous form, except that while the program is executed as a detached process without a console window, it allows the program to create a console later if required. Some programs, such as ssh (Secure Shell) require this option.
8	exec “`+`progname args” New in version 6.3.3: New option for WINE to execute with terminal Used to executing a child program that needs a terminal from a Wine version of sagewc/srepwc on Linux. See Wine programs section on how to define the terminal. Note: In this case the exit value returned by the program is not saved in sys.Status. It is lost due the fact the exit value returned by the program is not saved in sys.Status. As the GUI Termninal executed is not returning the command exit code.

command

The operating system command line to be executed. It may be a text constant, an alphanumeric field, or a concatenation of several such items. It should form the name of the program to be called, together with any arguments required by that program.

Ensure that any arguments that may contain internal spaces are enclosed in double quotes, since otherwise the text strings before and after each space are treated as separate arguments. Single quotes should not be used because some operating systems treat the single quote character in a command line as an ordinary character, without special meaning.

In a string constant, the backslash character may be used to specify that the double quote character immediately following it should be treated as a double quote, rather than as the end of the string. This is illustrated in the following example:

exec “-sagewc myprog \”" + tmp.Ref / “\”"

The field “tmp.Ref” , which may contain embedded spaces, is to be treated as a single argument by the program called, which will reference it as sys.Arg[3]. The syntax shown passes the value of tmp.Ref enclosed in double quotes. Note the space after “myprog”, which is required to separate it from the next argument, and the use of the + concatenator, which preserves trailing spaces, rather than the / concatenator, which does not.

Note

The exec command fails on DOS/Windows if the text contains a quoted string with a single “\” character in a pathname. This happens because “\” is an escape character in a quoted string, used to remove any special meaning from the character that follows it. The correct syntax is to use “\\” for each single “\” required. However, in many cases a “/” can be used instead; DOS and Windows accept this in a pathname unless it’s an argument to a DOS command.

[stdin = #channel]

[stdout = #channel]

The parent program can communicate with the standard input and standard output channels of the child process by means of these optional clauses. The channel number must be an integer expression in the range 1-64. Note that different channels must be used for stdin and stdout.

Use the put[field] # command to send data to the child process’s standard input channel, and the get[field] # command to receive data from its standard output channel.

If the stdin and/or stdout clause is used, it is essential that the form:

exec “-program args… &”

is used. If the leading minus sign is omitted, the resulting DOS box will reset stdin and stdout according to its own rules. If the ampersand is omitted, the parent will wait for the child program to exit before returning from the exec. See Example 4 below. See also Sequential files.

If it is also necessary to receive the output from stderr (standard error), use the execute() function instead of exec.

[on server_name]

The optional on server_name clause is used to execute a process on a remote server. The server must be running the Sculptor keyed file server program kfserver | kfservnt.

If the command ends with an ampersand (“&”), the process is started and the exec returns immediately. Otherwise, the exec waits, and the exit status of the process is returned in sys.Status.

If a connection to the server cannot be made, sys.Status is set to -1.

It is not possible to use both the stdin = and stdout = clauses when using exec on a server.

Child task termination code¶

The termination code of the child process is returned in the Sculptor system variable sys.Status. Sculptor programs can issue a termination status by adding it as an argument to the exit command.

The execu command¶

The execu command is identical to exec, except that if the program to be executed is an MS-DOS command and is executed by creating a DOS shell (no “-” prefix), the execu command causes it to be run minimised (unseen by the user). On UNIX, execu informs Sculptor that the program does not send output to the terminal, so Sculptor does not reset the terminal to standard mode before executing the program.

Wine programs¶

New in version 6.3.3: New option for WINE to execute with terminal

An entry 3 in the Special Text section has been added. This defines the terminal to be used when executing a child program that needs a terminal from a Wine version of sagewc/srepwc on Linux. Sample entries are provided and the default has been set to gnome-terminal. Uncomment the required terminal or comment out the default and add a new one.

Precede the exec command with a + to tell Sculptor that a terminal is needed. Example:

exec "+srep myreport nullp >report.txt"

NOTES

Forms of exec with a leading minus sign (no command shell) may not be used with built-in commands (such as dir) which are part of the command processor command.com.
The execute() function provides more advanced execution and control of a child process running concurrently.
If exec is used to call the Sculptor utility newkf, in order to reinitialise files used in the program, then these files should be closed before the exec, and reopened upon returning. Failure to do this can cause file corruption on some operating systems. The recommended method of creating a new file from within a program is openfile file_id create. In this case there is no need to close the file first.
The chain command is used to terminate the current program and call another.

EXAMPLE

Copy a file

exec "copy oldfile newfile"
A more complex exec line involving a pipe. Note the space at the end of “printinv”, which is necessary to prevent the word running into the next argument. The string concatenator “+” preserves trailing spaces from the previous word.

exec "srep printinv " + printer + "|" + spooler
A simple exec line. No need to call a new shell.

exec "-sagewc stock"

Redirect the standard input and output of the child task, enabling communication.

exec "-sagewc newprog &" stdin = #2 stdout = #3
put #2 "This is a message to the child program"
flush #2
get #3 "This is the child's reply"

RELATED TOPICS