  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Four — Flow Control (continued)
Overview
The RunBackgroundScript loads a specified script and runs the script from an optional entry point as a background thread. Optional parameters can be passed to the target script. After processing the target script is unloaded.
Syntax/Parameters
Syntax
handle = RunBackgroundScript ( string name, [string function], [parameters ...] );
Parameters
name
A string containing the name of the script to run. If name contains a qualified path, that file is loaded and run from that location. If the path is not qualified, it is resolved using the calling scripts main module path.
function
A string containing the name of the function to run. If omitted or empty, the default entry point is located and run. If there is no default function such as “main” or “entry”, the script will be run from an unstructured entry point in which case the parameters will not be retrievable by the executed script.
parameters
Zero or more optional parameters to pass to the script. Variables cannot be passed by reference. When parameters are employed, the function parameter must be provided. However, it can be a simple "" empty string. Only certain types of handles cannot be passed, see Remarks below for details.
Return Value
Returns a handle to the created thread or NULL_HANDLE on failure. Use the GetLastError function to retrieve a formatted error code.
Remarks
The RunBackgroundScript function loads the script and runs it from the specified point. A new thread is created for the specified script. Once the new script engine has been created, the RunBackgroundScript will return immediately with a handle or an error. If the provided script contains errors, the function will still return a handle and the errors will be processed by the background manager. In such a case, the thread will terminate nearly immediately.
See Section 4.14 Control and Background Processes for more information.
Certain restrictions apply to the background script. First and foremost is that background scripts (or any thread) cannot execute in the primary thread’s message loop. Because of this, modal dialogs and message boxes are not allowed. The MessageBox function can be used but will post a request to the frame and immediately return to the calling script. Background scripts can send messages to windows and execute SDK functions that require messages but the message must be run in the primary process thread. If the thread is busy (such as running another script), the background thread will be suspended until the message can be processed.
When passing a parameter as a handle, only global or Windows handles can be passed. For example, a handle to an object that is owned by the current script cannot be passed and used by the receiving script. However, the script handle can be passed.
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.