  |
GoFiler Legato Script Reference
Legato v 1.5b Application v 5.24b
|
| Table of Contents | < < Previous | Next >> |
Chapter Five — General Functions (continued)
Overview
The SetUnwindFunction function sets the function name of a function that will process an unwinding of the script either from an error or as part of a natural exit.
Syntax/Parameters
Syntax
int = SetUnwindFunction ( string function );
Parameters
function
A string containing a function name. If the function does not exist, the function will return an error. As this is a runtime function, the function need not be prototyped.
Return Value
Returns an int as ERROR_NONE or a formatted error code on failure.
Remarks
Under certain circumstances it can desirable or even required to clean up after a script error or during normal exit of a script. By default, Legato will close all handles and complete and pending operations on the referenced object. However, in some cases the script may be working with an external system or web site and need to perform more complex cleanup. An ‘unwind’ function can be used to complete any pending processing.
Upon exit of the run function within the script engine, the engine will check to see if an unwind function has been defined. If so, it is run. The unwind function does not change the script return value.
Upon entry, all global objects that have not been closed are available for processing. This allows for cleanup of things such as SQL transactions and other information. Since the unwind can be using global handles, it is important or the main body of the script to clear such global variables as they are closed using either zero or NULL_HANDLE.
An example of a script error causing an unwind:
handle hWP;
int main() {
SetUnwindFunction("unwind");
hWP = WordParseCreate(WP_GENERAL, "ThisIsATest");
FormatString(); // <-- Causes missing parameter error
MessageBox('i', "In main, no force");
return 0;
}
void unwind() {
int rc;
string s1;
rc = GetLastError();
s1 = WordParseGetWord(hWP);
if (s1 == "") { s1 = "ERROR on handle"; }
MessageBox('i', "Unwind - %08X\r\r%s", rc, s1);
CloseHandle(hWP);
}
In the example, the function called “unwind” is set as the unwind function. A simple object, word parse, is created and loaded with some data. Since it is global, it is available to all function. Locally defines handles should be avoided, if additional processing is required, since they will be closed as the local routines are popped off the program stack.
When the unwind completes, any handles that remain open will be closed.
Note that the first statement in the unwind function is GetLastError, that is how the script can determine if a program error occur or it was a normal exit. The ForceScriptError function can be used to pass an error to the unwind or test the closure of a script.
Only one unwind function is allowed and it will only operate at the global level.
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.