Lugaru's Epsilon

Epsilon User's Manual and Reference
   Primitives and EEL Subroutines
      Operating System Primitives
         . . .
         Calling Windows DLLs
         Running a Process
            Concurrent Process Primitives
            Other Process Primitives

Previous   Up    Next
Concurrent Process Primitives  Primitives and EEL Subroutines   Control Flow

Epsilon User's Manual and Reference > Primitives and EEL Subroutines > Operating System Primitives > Running a Process >

Other Process Primitives

int pipe_text(char *input, char *output, char *cmdline,
              char *curdir, int flags, int handler)
my_handler(int activity, int buf, int from, int to)  // Sample.
int buf_pipe_text(int inputb, int outputb, char *cmdline,
                  char *curdir, int flags, ?int errorb)

The pipe_text( ) subroutine runs the program specified by cmdline, passing it the contents of a buffer as its standard input, and inserting its standard output into a second buffer (or the same buffer).

The input buffer name may be NULL if the process does not require any input. Epsilon provides a current directory of curdir to the process. It passes Epsilon's current directory if curdir is NULL or "". This subroutine returns 0 and sets errno if the function could not be started, or returns 1 if the function started successfully.

The PIPE_SYNCH flag means don't return from the subroutine until the process has finished. Without this flag, Epsilon starts the subprocess and then returns from pipe_text( ), letting the subprocess run asynchronously.

The PIPE_CLEAR_BUF flag means empty the output buffer before inserting the process's text (but do nothing if the process can't be started); it's convenient when the input and output buffers are the same, to filter a buffer in place.

The PIPE_NOREFRESH flag tells Epsilon not to refresh the screen each time more data is received from the process, and is most useful with PIPE_SYNCH if you don't want the user to see the data until after it's been postprocessed in some way.

The PIPE_KEEP_ENV flag prevents Epsilon from modifying the environment it passes to the subprocess. By default, it passes settings such as EPSRUNS=P to the subprocess.

The PIPE_SKIP_SHELL flag makes Epsilon directly invoke the specified program, instead of using a shell as an intermediary. This results in improved performance, but command lines that use shell meta characters (like >file for redirection, | for pipelines, or file pattern wildcards) won't operate as desired. Only Epsilon for Unix supports this flag. When Epsilon prepares an argument list from the command line, it interprets and removes quotes which may surround arguments that contain spaces.

If handler is nonzero, it's the index of a function (that is, an EEL function pointer) to call each time text is received from the process, and when the process terminates. The handler function will be called with the buffer number into which more process output has just been inserted, and from and to set to indicate the new text. The parameter activity will be NET_RECV when characters have been received, or NET_DONE when the subprocess has exited. In the latter case from will hold the process exit code.

The command inserts text in a buffer at its type_point (see the previous section), the same as other functions that insert text into a buffer in the background.

Epsilon sets the buffer-specific process-exit-status variable in the output buffer to the value PROC_STATUS_RUNNING when a process starts, and sets it to the process exit status (or 0) when the process exits.

The pipe_text( ) subroutine described above is implemented using the buf_pipe_text( ) primitive. There are a few differences between these:

The buf_pipe_text( ) primitive uses buffer numbers, not buffer names. It won't create a buffer for you the way the subroutine will; the buffer must already exist. (Pass 0 for a buffer number if you don't need input.)

Instead of passing a function pointer for handler, you must instead set the buffer-specific when_activity variable in the output buffer prior to calling buf_pipe_text( ).

Pass a curdir of "", not NULL, to buf_pipe_text( ) to use Epsilon's current directory.

The buf_pipe_text( ) primitive accepts an additional, optional, parameter errorb. If nonzero, any output of the program sent to standard error will be sent to the errorb buffer instead of the outputb buffer. If errorb is zero, such output will appear in outputb along with standard output.

int winexec(char *prog, char *cmdline, int show, int flags)
/* Pass these values to winexec: */
#define SW_HIDE             0
#define SW_SHOWNORMAL       1
#define SW_SHOW             5
#define SW_MINIMIZE         6
#define SW_SHOWNA           8
#define SW_RESTORE          9

In Epsilon for Windows, the winexec( ) primitive runs a program, like the shell( ) primitive, but provides a different set of options. Normally, the second parameter to winexec( ) contains the command line to execute and the first parameter contains the full path of the program to execute.

The third parameter to winexec( ) specifies the window visibility state for the new program. It can be one of the values listed above.

The fourth parameter contains flag bits. The SHELL_KEEP_ENV flag prevents Epsilon from putting EPSRUNS=Y into the environment of the process it starts, as it does by default. The SHELL_SYNCH flag tells Epsilon to wait for the program to finish before returning from the winexec( ) primitive. By default, the primitive will return immediately.

This primitive returns the exit code of the program it ran. If an error prevented it from running the program, it returns -1 and puts an error code in the global variable errno. When the primitive runs a program without waiting for it to finish, the primitive returns zero if the program started successfully.

int run_viewer(char *file, char *action, char *dir)

The run_viewer( ) primitive runs the program associated with the given file, using its Windows file association. The most common action is "Open", though a program may define others, such as "Print". The dir parameter specifies the current directory in which to run the program. The primitive returns nonzero if it was successful, or zero if it could not run the program or the program returned an error code. This primitive always returns zero in the Unix version of Epsilon, which uses a shell script epsilon-viewer to run a viewer.

Previous   Up    Next
Concurrent Process Primitives  Primitives and EEL Subroutines   Control Flow

Lugaru Copyright (C) 1984, 2018 Lugaru Software Ltd. All Rights Reserved.