  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Seventeen — Application Integration Functions (continued)
When the application starts, it moves through an initialization process to setup various DLLs, initialize data structures, read settings and preferences and possibly start the GUI (Graphical User Interface).
The following graphic is a simplified diagram of the process:
 |
Base Initialize — Sets up all the components, all them to initialize, retrieve certain data. Instance Pass — If another instance of the application is running and the /NoNewInstance option is not present, the execution is passed to a running instance of the program including command line arguments. Ribbon Load — The custom or vendor provided ribbon and support structure. Preference Load — Load the application settings for the workstation and the user including all command line overrides. Script Startup — The Application startup is run. Syntax or script errors can stop the application from continuing. API Processing — If command line API verbs are provided, they are processed, and the application exits. GUI Run — The application passes execution to the primary message loop and the application frame. In addition, the command line is passed to the frame. If any files or other functions are to be run, they are run at this time. |
||
17.2.2 Creating a Startup Script
The Application Startup Script is simple and basically looks for any “*.ms” (menu script) files in the Scripts Extension folder, then the Script folder and finally in the user’s roaming profile under the vendor folder under the folder “Extensions”, for example, “Novaworks\Extensions”. Programmers should place their scripts in the Extensions folder and should avoid editing vendor provided scripts. To replace a vendor script, simply place it into the Extensions folder. If existing script hooks are replaced, the user script must delete existing hooks.
Basic structure (found at “C:\[Program Files .. \ Application ]\Scripts\ApplicationStartup.ls”) (note that the contents of the startup script are subject to revision or encryption):
/****************************************/
/* ** Prototypes */
int load_extensions (string); /* Extension Routine */
/* */
/* ** Global */
string errors; /* Error List */
string s_props[]; /* Script Properties */
/****************************************/
int main() { /* Entry From Application */
/****************************************/
string fnBase, fnMS; /* Path */
int rc; /* Return/Result Code */
/* */
/* ** Overall Application Initialize */
/* * Initialize */
fnBase = GetScriptFolder(); /* Get the script folder */
/* * Check and Run Application Init */
fnMS = fnBase + "ApplicationInitialize.ls"; /* Create name */
if (DoesFileExist(fnMS)) { /* There is an init script */
rc = RunScript(fnMS); /* Run the script */
if (IsError(rc)) { /* Something bad happened */
return ERROR_EXIT; /* Pass the error back and exit */
} /* end error */
} /* end has init script */
/* * Application/User Extensions */
fnBase = fnBase + "Extensions\\"; /* Go to extensions folder */
load_extensions(fnBase); /* Load the extensions */
/* * Run the Vendor Extensions */
fnBase = GetScriptFolder(); /* Get the script folder */
load_extensions(fnBase); /* Load the extensions */
/* * Run Extensions */
fnBase = GetApplicationDataCommonFolder(); /* Get the user extensions folder */
fnBase = fnBase + "Extensions\\"; /* Go to extensions folder */
load_extensions(fnBase); /* Load the extensions */
/* * Errors */
if (errors != "") { /* Bad scripts */
MessageBox('I', /* Error message */
"One more scripts had an error:\r\r%s", errors); /* and detail */
} /* end error */
return ERROR_NONE; /* Exit */
} /* end routine */
/****************************************/
int load_extensions(string fnBase) { /* Initialize Extensions from Location */
/****************************************/
handle hEnum; /* File Enumeration Handle */
string fnMS; /* Base Path, Menu Script */
string app_code; /* Application Code */
string s1; /* General */
int rc; /* Return/Result Code */
/* */
/* ** Run Menu Hooks/Extensions */
/* * Initialize */
fnMS = fnBase + "*.ms"; /* Create the wildcard match name */
hEnum = GetFirstFile(fnMS); /* Try to get the first file */
if (hEnum == 0) { /* Nothing found */
return ERROR_NONE; /* Just leave */
} /* end no handle */
app_code = GetApplicationCode(); /* Get who we are */
/* * Loop and Process Each Menu Script */
fnMS = GetName(hEnum); /* Get the name of the file */
while (fnMS != "") { /* Loop until no more files */
fnMS = fnBase + fnMS; /* Create qualified filename for script */
/* o Check Product */
s1 = ScriptGetComments(fnMS); /* Get the pragma comments */
if (s1 != "") { /* Has comments */
s_props = ParametersToArray(s1); /* Translate to array */
if (s_props["Platform"] != "") { /* Platform restricted */
rc = ScanString(s_props["Platform"],app_code);/* Test for platform in list */
if (IsError(rc)) { /* Not Found */
GetNextFile(hEnum); /* Get the next item from the folder */
fnMS = GetName(hEnum); /* Get the name */
continue; /* Go back for more */
} /* end skip */
} /* end has platform */
} /* end product comments */
/* o Run the Script for Setup */
rc = RunScript(fnMS, "setup"); /* Run the script to get it to setup */
if (IsError(rc)) { /* Something bad happened */
errors .= GetName(hEnum) + " "; /* Add to errors */
} /* end error */
GetNextFile(hEnum); /* Get the next item from the folder */
fnMS = GetName(hEnum); /* Get the name */
} /* end loop for files */
/* * Wrap Up */
CloseHandle(hEnum); /* Release the enumeration object */
return ERROR_NONE; /* Just leave, continue startup */
} /* end routine */
As can be observed, this simple script first runs a script called “ApplicationInitialize.ls”, if available. It then creates a wildcard mask for *.ms in the same folder as the startup script. Each of those files is then run and made to execute at the “setup” function.
In addition, since the user folder could be shared by more than one application, a ‘Platform’ pragma comment can be added to restrict which applications will attach the user scripts. If the platform is not specified, it is assumed the script can be added.
Generally, the application initialize script allows custom setup of the entire application and will allow the application startup cycle to be stopped at the discretion of the script.
If this file contains errors, it will stop the application from starting up. The error messages will be dumped in the application log located at: “%appdata%/Novaworks/[application name].log”. This will also result in a stop message:
as an unfriendly warning that something went terribly wrong. In addition, the application startup must be accessible from the application with read permission. If an error occurs other than File Not Found or Path Not Found, the application startup sequence will be terminated. An example message:
In this case, the error 0x00000020 is a sharing violation indicating a program has the file open exclusively. These errors stop the application’s startup because they indicate a serious condition that could prevent the application from operating as intended. For example, suppose that the ApplicationInitialize.ls script contains a production “check-in” feature. Should the overall script fail to run correctly, the application should not start.
As mentioned previously, developers should refrain from modifying this file and instead they should add “.ms” files. This will help avoid the above errors as well as avoid an unintentional change to the behavior of the base startup scripts during a normal update cycle.
By adding a folder, “LegatoLogs”, within the application data folder for the user (normally at the location “%appdata%\Novaworks”), Legato will automatically write an XML log file using the current tick count and the extension “.log”. The file is transitory since a message is posted to immediately display and the file deleted, If the folder is not present, the log is essentially lost on each execution.
The last step in the application startup is the Run GUI phase. After the frame window (application desktop) has been initialized, and prior to running any command line or other parts of the initialization, the frame will run any scripts added to the initialization cycle by the AddFrameInitializeFunction function.
While the files executed at startup are known as “menu scripts”, they can contain any type of operation. The principal concept is that the “setup” function is run, allowing for the script to hook itself into the operation of the application.
Multiple hooks can be added to a single file. While there are no constraints on the structure of menu scripts, it is generally desirable to group certain menu function processing within a single file. For example, if a pre-filing production process was to be run, these could be grouped into a single file while in another case, document control functions hooking the new, open and save operations in another script.
After the script has been run via the ‘setup’ routine, it is discarded. It will not be reloaded until the first time a hook is run. See Section 17.6 Menu Hooks for additional information.
| 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.