Process Library

• Abstruct
• Index
• Structs
• Variables
• Functions
• Event Handler
• Implementation Code

Abstract

The VCSSL Process library is a standard library for communicating with the operating system and for launching and controlling processes.It can also exchange data with launched processes through standard input and output.

The Process library provides features such as executing operating-system commands from VCSSL and launching other applications.It is also needed when linking a VCSSL program with programs developed in languages other than VCSSL.

The basic flow of process control in VCSSL is as follows.

First, create a process with the newProcess function.At this point, execution has not started yet. This function assigns and returns a process-specific ID, called the process ID(the process ID here is assigned by the VCSSL implementation, and generally does not match the ID assigned by the operating system).

Next, start execution of the process with the startProcess function.Process execution is performed asynchronously with respect to VCSSL program execution.In other words, VCSSL processing continues without waiting for the process to finish.If you want VCSSL-side processing to wait until the process ends,use the waitForProcess function.

When the process finishes, the onProcessEnd event handler is called.There you perform tasks such as disposing of the process.

There are two ways to obtain the standard output of a process.One is to call the getProcessOutput function and retrieve it actively at any timing.This is convenient, for example, when you want to obtain the entire standard output after the process has finished.The other is to retrieve it passively by using the onProcessOutput event handler.This is convenient when you want to return responses to standard input according to the received standard output.However, in that case, note that the standard output is buffered, probably line by line,and there may be a time lag before it is passed to the event handler, especially when the process is waiting for input without outputting a newline.For interactions where this time lag becomes a problem, call theflushProcessOutput function as needed from loops or elsewhere,and flush the buffer at appropriate times.If standard output or error messages become garbled, set the character encoding by usingsetProcessOutputEncoding and setProcessErrorEncoding.

By default, the working directory of a created process is the directory containing the VCSSL script, that is, the main directory.You can set the working directory as needed by using setProcessWorkingDirectory.Note that it is not automatically set to the directory containing the process executable.Also note that the working directory of a process may not always be set as expected depending on the environment, and the same applies to the default directory.For example, on classic shells and command-line terminals, special paths that cannot be set as the current directory may fail to be assigned as the working directory.A known concrete example is a UNC-format path pointing to a directory on the network that is not connected as a network drive.

To control conditions such as the working directory more reliably and make debugging easier, it is effective to use methods such as wrapping the execution command in a shell script and setting the working directory inside that shell script.

Index

int newProcess( string command[ ] )

Creates a process for a native application, assigns its unique identifier called a process ID, and returns it.After creating the process with this function, execution does not start until startProcess is called, since VCSSL 3.3, so you can set standard input and other properties in the meantime.Processes can also be created by System.exec, but exec starts execution at the same time as process creation.For example, to start "test.exe" with the command-line arguments "1", "2", and "3", after importing the File and Process libraries:string command[] = { getFilePath("test.exe"), "1", "2", "3" }int processID = newProcess(command);and so on. To start execution, then call:startProcess(processID);To wait until it finishes, then call:waitForProcess(processID);By default, the working directory of the created process is set to the directory containing the VCSSL script, that is, the main directory.You can set the working directory as needed by using setProcessWorkingDirectory.In either case, it may fail to be set for special path formats. See the overview at the beginning of this page for details.

int newProcess( string command )

Creates a process for a native application, assigns its unique identifier called a process ID, and returns it.Basically, it provides the same function as newProcess(string command[]), but you can write the command as a single line like in a command-line terminal without splitting the arguments into an array.This is convenient, but because how the contents are split depends on the environment and implementation, it can instead lead to behavior that is harder to debug when running on different environments or after version changes.If it does not work as expected, or if you want to emphasize future stability, using newProcess(string command[]) with arguments explicitly split into an array is recommended.

void startProcess( int processID )

Starts execution of a native application process.After execution starts, processing is performed asynchronously and independently of VCSSL execution.If you want VCSSL-side processing to wait until the process finishes,call waitForProcess.

void deleteProcess( int processID )

Disposes of the resources related to a native application process. Call it after the process has finished executing.However, it must not be called while the process is still running. To dispose of a process during execution,first terminate it forcibly with destroyProcess.

void destroyProcess( int processID )

Forcibly terminates a native application process while it is running.

void setProcessInput( int processID, string command )

Sets the standard input content to be passed to the process.The input content is buffered and passed to the process when the process actually enters a waiting-for-input state.Therefore, you can also set all standard input needed until the process finishes at once, separated by newline characters.For example, to input "1", "2", and "3" in sequence:setProcessInput(processID, "1" + EOL + "2" + EOL + "3" + EOL);and so on.If the input becomes garbled, set the character encoding appropriate for the process with setProcessInputEncoding.Also, instead of relying on buffering, you can perform standard input interactively, that is, step by step, together with obtaining standard output.In that case, depending on the environment, the input may not be accepted unless a newline character is appended at the end.

string getProcessOutput( int processID )

Gets the standard output content of the process buffered up to the time of the call.Depending on the environment, there may be a limit on the buffer size, or efficiency may decrease as the buffer accumulates.Therefore, for native applications that produce a large amount of standard output,clear the buffer as needed with clearProcessOutput.If the retrieved content becomes garbled, set the character encoding appropriate for the process with setProcessOutputEncoding.

string getProcessError( int processID )

Gets the standard error output content of the process buffered up to the time of the call.Depending on the environment, there may be a limit on the buffer size, or efficiency may decrease as the buffer accumulates.Therefore, for native applications that produce a large amount of standard error output,clear the buffer as needed with clearProcessError.If the retrieved content becomes garbled, set the character encoding appropriate for the process with setProcessErrorEncoding.

void clearProcessOutput( int processID )

Clears the standard output buffer of the process.For native applications producing a large amount of standard output,clear it as needed because efficiency may decrease as the buffer accumulates.

void clearProcessError( int processID )

Clears the standard error output buffer of the process.For native applications producing a large amount of standard output,clear it as needed because efficiency may decrease as the buffer accumulates.

void flushProcessOutput( int processID )

Flushes the standard output buffer of the process.When flushed, all content buffered at that point is sent toonProcessOutput.

void flushProcessError( int processID )

Flushes the standard error output buffer of the process.When flushed, all content buffered at that point is sent toonProcessError.

void setProcessInputEncoding( int processID, string inputEncoding )

Sets the text encoding of the standard input passed to the process.This setting must be made before using the standard input of the process.If it is set after some standard input has already been performed, it may not be applied.

void setProcessOutputEncoding( int processID, string outputEncoding )

Sets the text encoding of the standard output content of the process.This setting must be made before using the standard output of the process.If it is set after some standard output has already been performed, it may not be applied.

void setProcessErrorEncoding( int processID, string errorEncoding )

Sets the text encoding of the standard error output content of the process.This setting must be made before using the standard error output of the process.If it is set after some standard error output has already been performed, it may not be applied.

void setProcessWorkingDirectory( int processID, string workingDirectoryPath )

Sets the working directory of the process.This setting must be made before starting execution of the process by startProcess.If it is set after execution starts, it will not be applied.If you execute the process without setting a working directory, the directory containing the VCSSL script, that is, the main directory, becomes the working directory.Note that this is not the directory containing the executable file of the process.Also note that the working directory of the process may not always be set as expected depending on the environment, and the same applies to the default directory.For example, on classic shells and command-line terminals, special paths that cannot be set as the current directory may fail to be assigned as the working directory.A known concrete example is a UNC-format path pointing to a directory on the network that is not connected as a network drive.To control conditions such as the working directory more reliably and make debugging easier, it is effective to use methods such as wrapping the execution command in a shell script and setting the working directory inside that shell script.

int getProcessExitValue( int processID )

Returns the exit status code of the process.

void waitForProcess( int processID )

Waits on the VCSSL side until execution of the process finishes.

---

Event Handlers

void onProcessStart(int processID)

Called when a process is created.

void onProcessEnd(int processID)

Called when a process ends.

void onProcessOutput(int processID, string output)

Called when a process writes to standard output.However, because the output content is buffered, this handler is not called at the exact moment when output is produced, and there is a time lag.The timing at which the buffer is flushed strictly depends on the implementation, but it is probably normally line by line.In that case, the output content is also passed to this event handler line by line(however, for very long lines that exceed the buffer capacity of the implementation, the content of one line may be split and passed in multiple calls).To forcibly flush the buffer at any timing without waiting for a newline, use the flushProcessOutput function.If the output content becomes garbled, set the character encoding appropriate for the process with setProcessOutputEncoding.

void onProcessError(int processID, string output)

Called when a process writes to standard error output.However, because the output content is buffered, this handler is not called at the exact moment when output is produced, and there is a time lag.The timing at which the buffer is flushed strictly depends on the implementation, but it is probably normally line by line.In that case, the output content is also passed to this event handler line by line(however, for very long lines that exceed the buffer capacity of the implementation, the content of one line may be split and passed in multiple calls).To forcibly flush the buffer at any timing without waiting for a newline, use the flushProcessError function.If the output content becomes garbled, set the character encoding appropriate for the process with setProcessErrorEncoding.

Structs

- None -

Variables

- None -

Functions

Event Handlers