GoFiler Legato Script Reference   Legato v 1.4j Application v 5.22b

Table of Contents	< < Previous	Next >>

 

Chapter Four — Flow Control (continued)

CreateProcess Function

Overview

The CreateProcess function creates a new process in the primary thread that runs a requested program. This function returns immediately.

Syntax/Parameters

Syntax

handle = CreateProcess ( string name, [string parameters], [int showmode] );

Parameters

name

A string containing the name of the program to run. This should generally be a qualified name and path referencing an executable (“exe”) file.

parameters

An optional string that specifies the parameters to be passed to the called program. The parameters and their syntax are dependent on the receiving application. For many applications, placing a filename as a parameter will cause the target program to open and process that file. Note that most applications will treat unquoted text with spaces as multiple parameters and therefore the parameters must be appropriately prepared.

showmode

An optional int specifying the requested mode to show the called application, assuming it is a window. These flags match those in the Windows SDK; for more information, see MSDN. The default is SW_RESTORE.

SW_HIDE

Hides the window and activates another window.

SW_MAXIMIZE

Maximizes the specified window.

SW_MINIMIZE

Minimizes the specified window and activates the next top-level window in the z-order.

SW_RESTORE

Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.

SW_SHOW

Activates the window and displays it in its current size and position.

SW_SHOWDEFAULT

Sets the show state based on the SW_ flag specified in the startup info structure passed to the CreateProcess‡ function by the program that started the application. An application should call ShowWindow‡ with this flag to set the initial show state of its main window.

SW_SHOWMAXIMIZED

Activates the window and displays it as a maximized window.

SW_SHOWMINIMIZED

Activates the window and displays it as a minimized window.

SW_SHOWMINNOACTIVE

Displays the window as a minimized window. The currently active window remains active.

SW_SHOWNA

Displays the window in its current state. The currently active window remains active.

SW_SHOWNOACTIVATE

Displays a window in its most recent size and position. The currently active window remains active.

SW_SHOWNORMAL

Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.

Note that not all programs process this parameter in the same manner and some override its operation depending on the mode requested. For example, Internet Explorer ignores all modes except SW_HIDE.

Return Value

Returns a handle as a process handle or a NULL_HANDLE on failure. Use the GetLastError function to retrieve error information.

Additional process information can be retrieved by using the GetLastErrorMessage immediately after execution of the CreateProcess function. A parameter string of the following format will be returned:

hProcess: 0x00000000; hThread: 0x00000000; dwProcessId: 0x00000000; dwThreadId: 0x00000000

The hProcess value is the same as the returned handle. The other values can be used to identify the primary thread and the IDs for the process and primary thread. Use the GetParameter and HexToInteger to convert the values.

Remarks

The CreateProcess function differs from RunProgram [or ShellExecute] in that a program must be run. The others “shell out”, meaning they can run a default program based on a file extension. The CreateProcess function will return almost immediately with the process handle; it does not wait for the called program to complete its execution. To wait for the program to close, use the WaitForObject function with the process handle. The return value of the program can also be retrieved with the GetProcessExitCode function.

Example

The following example is a section of code that launches the command line version of a program called Arelle, which validates an XBRL file set and returns an XML log. At the start of this segment, the progress window is open, fnInstance is a string containing the filename, and fnLog is a string containing the destination log filename. The variable s1 has been defined as a string and hAP is defined as a handle.

                                                                        // ** Run Arelle
                                                                        //  * Setup Progress
    ProgressSetStatus(1, "Running Arelle");                             // Progress line 1
    ProgressSetStatus(2, "");                                           // Progress line 2
                                                                        //  o Create Query
    s1 = "-vf \"" + fnInstance + "\" --logFile \"" + fnLog + "\" ";     // Start of query
    s1 += "--disclosureSystem efm";                                     //   add check type
                                                                        //  o Run and Wait
    hAP = CreateProcess("C:\\Program Files\\Arelle\\arelleCmdLine.exe", // Run the process
                        s1, SW_HIDE);                                   //   with options
    if (hAP == NULL_HANDLE) {                                           // Error loading
      rc = GetLastError();                                              // Get the error condition
      ProgressClose();                                                  // Close progress
      MessageBox('x', "Error %08X running Arelle", rc);                 // Display error
      return ERROR_EXIT;                                                // Exit Done
      }                                                                 // end error on export
                                                                        //  > Wait Loop
    s1 = "";                                                            // Use as tickler
    while (WaitForObject(hAP, 500) == (ERROR_SOFT | WAIT_TIMEOUT)) {    // Loop and wait
      s1 += ". ";                                                       // Add to tickler
      if (GetStringLength(s1) > 60) { s1 = ""; }                        // Reset tickler
      ProgressSetStatus(2, s1);                                         // Progress
      }                                                                 // end wait loop

The process is started and the handle is checked for an error. The script enters a loop and the called program’s progress is tickled with a leader of periods to indicate activity.

Related Functions

CallProgram

CreateProcessAsElevated — Creates an elevated process and returns with a process handle.

GetProcessExitCode — Retrieves the process return code for a completed process.

RunProgram — Runs another executable (exe) as a separate process and immediately returns.

RunProgramElevated

RunScript — Runs an external script in a separate script engine in the current process thread.

WaitForObject — Wait for an object with an optional specified time.

WaitForObjects

WaitForObjects

Platform Support

Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL

Legato IDE, Legato Basic

 

Table of Contents	< < Previous	Next >>

GoFiler Legato Script Reference — Generated on 04/22/2024

© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.