ProcessInitialize Function

Action

Initializes a process that is started later with the ProcessStart function.

To avoid memory leaks, make sure to call the ProcessFree function at the end of the script.

Include file

Kernel.bdh

Syntax

ProcessInitialize( in sCmdLine    :string,
                   in nFlags      : number optional,
                   in sParams     : string optional,
                   in sWorkingDir : string optional,
                   in sStdOutFile : string optional,
                   in sStdErrFile : string optional,
                   in nTimeOut    : number optional,
                   in sUser       : string optional,
                   in sPwd        : string optional ): number;

Return value

If the function is successful, a handle to the process is returned (the handle is greater than zero). This handle must be used for the other functions with the prefix Process.

In case of an error 0 is returned. The GetLastError function may be used to retrieve the system error code.

Parameter	Description
sCmdLine	Command line of the application to be started.
nFlags	Process related flags. You can use the following flags to influence the behavior of the executed application: PROCESS_ATTACHED: The started application is a child of the current process. If the current process is killed, the started process is automatically killed (e.g. when pressing "Stop" the process that was started with the function ProcessStart, is killed). Silk Performer waits for the child process to complete. PROCESS_DETACHED: The started process is not attached to the process that called it. Silk Performer waits for the new process to complete (you must use ProcessWait). PROCESS_PIPED: The output of the started process is sent to the Silk Performer GUI. The started process is automatically attached. If the current process is killed, the started process is automatically killed (e.g. when pressing "Stop" the process that was started with the function ProcessStart, is killed).
sParams	Parameters for the executed application.
sWorkingDir	Specifies the current drive and directory for the started process. If this parameter is NULL, the new process will have the same current drive and directory as the calling process.
sStdOutFile	The file where the output is sent to.
sStdErrFile	The file where the error output is sent to.
nTimeOut	TimeOut for the process in seconds. This parameter is only of importance when the process is started attached or piped. If the process doesn’t end within this time interval (in seconds), it will be terminated. If this parameter is not set or is set to zero, then the ProcessStart function will wait for the termination of the started process.
sUser	Account used to run the new process. If the account is not specified, the new process takes up the account of it's creator. Note: It is only possible to start the process in the context of another account if no other user is logged in. But it is possible to start a process if the script is executed in the context of a special account which is called system account. When running a test then under normal circumstances the system account is used. The user account of the process must have the SE_TCB_NAME privilege (in User Manager, this is the "Act as part of the Operating System" right). The SE_TCB_NAME privilege is very powerful and should not be granted to any arbitrary user just so that they can run an application that needs to validate credentials.
sPwd	Password for the account.

Example

dcltrans
  transaction TMain
  var
    hFile      : number;
    hProcessId : number;
    nStatus    : number;
    nRead      : number;
    sData      : string;
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize ("application1.exe", PROCESS_DETACHED,
                  "", "c:\\temp\\", "c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp", "c:\\temp\\");
    ProcessStart(hProcessId);

    // Wait for process to finish
    Wait(25.0);

    // Kill the process if it hasn't finished yet
    nStatus := ProcessGetState(hProcessId);

    if (nStatus <> PROCESS_STATE_FINISHED) then
      ProcessKill(hProcessId, PROCESS_KILLSINGLE);
    end;

    // Read the output of the process, written to a file
    FOpen(hFile, "c:\\temp\\out.txt", OPT_FILE_ACCESS_READ, OPT_FILE_OPEN);

    while FRead(hFile, sData, 1, nRead) do
      Write(sData);
    end;

    FClose(hFile);
    ProcessFree(hProcessID);
  end TMain;