GoFiler Legato Script Reference   Legato v 1.5b Application v 5.24b

Table of Contents	< < Previous	Next >>

 

Chapter Five — General Functions (continued)

AddMessage Function

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

ConsoleGetHandle — Returns the handle associated with a specified console or the default console.

ConsolePrint — Prints a message to the default or specified console.

CreateFile — Creates a basic file with optional access mode and characteristics.

LogCreate — Creates a general log object with an optional log name and target filename base.

LogDisplay — Displays the specified log as a tab in the Information View window.

LogExport — Exports a specified log to a file as XML, HTML or other formats.

LogSetMessageType — Sets the message type for the next message added.

LogSetProperty — Sets a specific property for the next message added.

LogSetTarget — Sets a target filename for the next message added (links message to file).

OpenFile — Opens the specified file as a Basic File Object.

PoolCreate — Creates a String Pool Object (SPO) and optionally loads the pool with a string.

Platform Support

Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL

Legato IDE, Legato Basic

 

Table of Contents	< < Previous	Next >>

GoFiler Legato Script Reference — Generated on 10/21/2024

© 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.