  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Five — General Functions (continued)
Overview
The AddMessage function allows the script to add a formatted message to a Log, Basic File, Pool or Console Object.
Syntax/Parameters
Syntax
int = AddMessage ( [handle hObject], string format, [parameters ...] );
Parameters
hObject
An optional handle to a Basic File, Pool, Log Object, Console or Application Log. If omitted, the default log handle is used. The handle can be a log object created with the LogCreate function, a Basic File object created with the OpenFile or CreateFile functions; or, a String Pool Object created with the PoolCreate function. When writing to a console, the handle must be a console window handle, not a pseudo console handle as an ID.
format
A string containing a template that specifies the structure of the resulting string. See Section 5.2 String Functions for information on creating formatted strings.
parameters
Zero or more parameters to be formatted and inserted into format. If no parameters are supplied, the template is simply passed through to the result string. A parameter value cannot resolve to a dimensional array.
Return Value
Returns an int as ERROR_NONE or a formatted error code on failure. Use the GetLastError function to retrieve error information.
Remarks
The handle can be the default log, a specified log, a file or a string pool object. When writing a log to a text file, the file buffer can be forced to be flushed by using the FO_FORCE_SPOOL option on the CreateFile and OpenFile functions when creating the log file. This causes the file to be written to, closed, and reopened. While slowing the operation, it forces the file to be flushed thus allowing for a high-level of data integrity if a program crash occurs and is therefore useful for debugging.
Current log entry properties, such as target or position, only apply to Log Object types.
Note that if the default log is used (no handle), it is up to the caller to the script to display the log. When using the IDE, the log will be displayed automatically (if it has content). If called as a hook, menu function or API, the default log will not be displayed.
Log messages added to a file are always automatically ended with a carriage return/new line (“/r/n”) line ending. Log entries added to a pool are terminated with a line ending in accordance to the object’s settings.
The application log is a log of all major operations performed by the application and their respective results. It is designed to store specific events to aid in troubleshooting. To write to the application log, use the synthetic handle APP_LOG_HANDLE for the hObject parameter. The application log has a pseudo structured format and programmers should attempt to remain in this format. The information not indented. Also note that the log is flushed on every write operation and as such can be slow. The log is normally stored in the application data area for the vendor by product name with a .log extension.
When called as a console app or from the IDE, the log is displayed after the script end execution. For the console, it is added at the very end, as such, do not use the AddMessage function to perform user queries. For Legato Basic in windows mode, the log is displayed as a window at the end of execution. For the IDE, it is displayed in the Information View pane. To print in real time, use the ConsolePrint function.
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.