Executing a child process

execute()

Execute a child process

SYNTAX

execute (server_name, command, directory, flags, show [, stdin, stdout, stderr])

Execute a child process, returning a handle to the new process. The child process runs concurrently with the parent.

If execute() is successful, it returns a handle to the child process. This handle must be stored in an i4 type field; it is used subsequently to control the child process and to retrieve information about it. The close_handle() function must be called when the handle is no longer required. Otherwise, system resources allocated to the child process will not be freed, even after the process has exited.

If execute() fails, it returns -1 and stores the current system error code in sys.Errno. There can be many reasons for failure, some of which may not generate a meaningful error code.

Note: There is a difference between Windows and Unix when the command can’t be found. In Windows the handle returned is -1 while in Unix a correct handle is returned and the handle exitcode() has to be checked for number 2 (ENOENT errno value).

server_name	The name of the server on which the task was run. This value should be set to NULL or to a null string if the task is a local process. Currently, stdin, stdout and stderr are not supported if the task is run on a server.
command	The program to be executed, and any arguments to the program. The command should be prefixed with “-” to avoid getting a command shell. A command shell is needed if the command contains I/O redirection. On UNIX (but not on Windows) a shell is also needed if there are any wild card arguments. A trailing “&” on the command is optional, because execute() always runs the child process concurrently. A trailing “&&” on the command avoids a delay under Windows. 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.
directory	The directory in which the program should start. Set this to NULL or a null string to start the program in the current working directory of the parent program.
flags	The creation flags argument to the CreateProcess() function (Windows only). Set flags to 0 to use standard options. Multiple flags are combined using the “|” operator. Some useful flags are defined in <sculptor.h> with the prefix EXEC_. This is an advanced feature for special requirements. Users should read the Microsoft documentation before using flags. This argument is not used under UNIX.
show	The requested show option for the child process. This must be one of the activation flags defined in <sculptor.h> with the prefix AA_. If there is no special requirement, the flag AA_SHOWNORMAL (activate and show in normal size and position) is recommended. Setting show to 0 causes the flag AA_HIDE to be used. The child process will be hidden. Many programs will override the show option when they start.
stdin	If non-zero, specifies a channel number. Sculptor creates a pipe that connects this channel in the parent program to the standard input channel of the child process. The put[field] # command can then be used to write messages to the child’s standard input: put #stdin putfield #stdin where stdin is the channel number assigned in this argument. The channel number specified for stdin must not be open when execute() is called, and must be closed using close # when no longer required: close #stdin If the child process is a Sculptor program, it can open its standard input channel using the open # command: open #channel, “stdin” read A Sculptor program can also read from its standard input using the get[field] # command: get #0 getfield #0 Channel 0 is the standard input channel. It may not be opened or closed.
stdout	If non-zero, specifies a channel number, which cannot be the same as stdin. Sculptor creates a pipe that connects this channel in the parent program to the standard output of the child process. The get[field] # command can then be used to read the child’s standard output messages: get #stdout getfield #stdout where stdout is the channel number assigned in this argument. The channel number specified for stdout must not be open when execute() is called, and must be closed using close # when no longer required: close #stdout If the child process is a Sculptor program, it can open its standard output channel using the open # command: open #channel, “stdout” create A Sculptor program can also write to its standard output using the put[field] # command and channel 0. This, however, is not recommended, because put #0 writes to the current report output when used inside a run report command. Messages written to stdout are buffered by the operating system and are only flushed when the buffer is full, the channel is closed, the program exits or an explicit flush # command is called. Programs that communicate through pipes must ensure that any output to a pipe is flushed before they wait for input on another pipe. This is done by means of the flush # command: flush #channel
stderr	If non-zero, specifies a channel number. Sculptor creates a pipe that connects this channel in the parent program to the standard error channel of the child process. The get[field] # command can then be used to read the child’s standard error messages: get #stderr getfield #stderr where stderr is the channel number assigned in this argument. The channel number specified for stderr must not be open when execute() is called, and must be closed using close # when no longer required: close #stderr stderr cannot be the same as stdin, but it can be the same as stdout, and this is often the most useful option. If the child process is a Sculptor program, it can open its standard error channel using the open # command: open #channel, “stderr” create Messages written to stderr are buffered by the operating system and are only flushed when the buffer is full, the channel is closed, the program exits or an explicit flush # command is called. Programs that communicate through pipes must ensure that any output to a pipe is flushed before they wait for input on another pipe. This is done by means of the flush # command: flush #channel

---

Note

The exec command also executes a child task but does not return a handle.

---

EXAMPLES

execute(NULL, "-srepwc prog4 &&", "/usr/jane/apps", EXEC_HIGH_PRIORITY, AA_SHOWNORMAL, 2, 8, 8)

!temp ExitCode,,i4
!temp Handle1,,i4

    tmp.Handle1 = execute(NULL, "-scc prog3", NULL, 0, AA_HIDE)
    if (tmp.Handle1 = -1) {
        error "Cannot run compiler. Error code: " + tostr(sys.Errno)
        exit
    }

    do {
          tmp.ExitCode = exitcode(NULL, tmp.Handle1, 500)
     }
          while (tmp.ExitCode == CHILD_PROCESS_RUNNING)

    switch (ExitCode) {
        case = 0:
            info "Program compiled successfully."
            break

        default:
            error "Source file compilation failed: exit code " + tostr(ExitCode)
            break
    }

---

RELATED TOPICS

close_handle()

end_process()

exitcode()

exec

Sequential files