  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Four — Flow Control (continued)
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_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
Platform Support
Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL
Legato IDE, Legato Basic
| Table of Contents | < < Previous | Next >> |
© 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.