LDC #61: Logging: Leaving Your Mark

Skip to blog entries
Skip to archive page
Skip to right sidebar

Friday, December 01. 2017

LDC #61: Logging: Leaving Your Mark

Today we’re going to talk about logs. Legato provides a number of input and output (I/O) methods. The choice and style of I/O can vary as much as programmers and users. Logs are a convenient method of keeping and relaying data without establishing a complex data formatting regiment. They are useful for reporting information to a user (such as the number of instances a search and replace operation changed the text, for example, or whether or not there were errors in an procedure). They are also employed by many high-level application functions, such as a validation function indicating a list of possible notices, warnings, and errors.

We’ve used logs in the past in Legato Developer’s Corner to display the results of other scripts, but in this article we’re going to go more in depth into how we can access and alter logs, as well as change the way a log looks to the user. Within a script, a log is created, added to, referenced, and displayed as a log object. A log object does not need to be displayed in the Information View. If it is, its appearance in the Information View is determined by the program section displaying the log and the content of the data.

The log object has certain properties that can be controlled, such as its name or the default target file. The object also contains a series of records, each with a display string and properties such as the severity of an error or the location to which the error applies. Like other objects we’ve discussed before, log objects are created and referenced via a handle, which is stored in a handle variable type.

There are three types of logs that can be referenced at all times using Legato: the global log, the default log, or a custom log. The global log is a is a shared log for the application. The contents of the global log object are subject to change because every script or function running in the program can modify the log. Every script that runs has also access to its own default log, which can be referenced by getting a handle to is using the
GetDefaultLog SDK function or by leaing handle references in functions blank. When a script finishes execution, it will show the default log if there is content in it. Finally, you can create a custom log using the LogCreate function.

Let’s take a look at an example using some of the functions available to us.

handle myLog;                                   /* Declare our log              */
myLog = LogCreate("This is a log");             /* Create our log               */

LogSetMessageType(3);                           /* Set to Warning               */
AddMessage(myLog, "Warning Message");           /* Output to log                */
LogIndent(myLog, 5);                            /* Indent the log               */
LogSetMessageType(1);                           /* Set to Info                  */
AddMessage(myLog, "Info Message");              /* Output to log                */
LogIndent(myLog, 40);                           /* Indent the log               */
LogSetMessageType(4);                           /* Set to Error                 */
AddMessage(myLog, "Error Message");             /* Output to log                */
LogOutdent(myLog, 10);                          /* Outdent the log              */
LogClearProperties();                           /* Clear Properties             */
AddMessage(myLog, "Message 4");                 /* Output to log                */
LogAddErrorSummary(myLog);                      /* Add Error Summary            */
LogDisplay(myLog);                              /* Display the Log              */

LogExport(myLog, GetScriptFolder() + "logoutput.xml"); /* Export the log        */

First of all we create a log using the LogCreate function and store the handle in the myLog variable. We can change the way the messages appear in the log using the LogSetMessageType function. For example, if we change the parameter passed to the LogSetMessageType function to 3, the script will display the message as a warning in the information view with purple text. This setting is script wide, meaning that every message that gets put into any log will be displayed with the current settings until we change them again.

We add a message to the log with the AddMessage function, and then we use the LogIndent function to move the next line over by 5 pixels. You can put in values anywhere from -40 to 40 into the LogIndent and LogOutdent functions, which will move the indentation from zero to 80, with zero being flush to the left.

We add a few more messages and message types until we clear the properties with the LogClearProperties function, which resets the internal settings variables affecting how the messages appear.

Finally we tell GoFiler to put the log in the Information View with the LogDisplay function.

The last thing that we do is we tell GoFiler to export the log with the LogExport function, which takes the handle to our log and a path to the resultant log file. The LogExport function can export a log to an HTML file, a CSV file, a plain text, or as an XML file. XML files that are logs, when opened in GoFiler, will open in the Information View.

This was an introduction to putting information into and then storing logs in GoFiler. In a later post we will talk about getting data from logs and linking logs to files.

Joshua Kwiatkowski is a developer at Novaworks, primarily working on Novaworks’ cloud-based solution, GoFiler Online. He is a graduate of the Rochester Institute of Technology with a Bachelor of Science degree in Game Design and Development. He has been with the company since 2013.