JadeLog Class

The JadeLog class encapsulates the behavior required to create text log files in JADE applications. (You cannot write to the default JADE log file, but you can use the features defined in this class to create a log file and output messages to that file.)

You can use this logging mechanism to output the following classes of messages.

Log messages, which are always output to the log file. A log message forces any pending output to the log file by forcing a flush of the output buffer to disk.
Trace messages, which are output to the log file only when a value has been specified for the selector property and the initialization of the application locates a parameter with the same name as the <selector‑name> parameter value in the [JadeLog] section of the JADE initialization file and this parameter is set to a non-zero value. The value in the selector property and the matching parameter name are case-insensitive.

For example, tracing is enabled if the selector property passed when the application starts up has a value of mylogging and the JADE initialization file contains the following:
```
[JadeLog]
MyLogging=1
```
If a parameter with a corresponding name is located in the JADE initialization file parameter when the application starts up but it is set to zero (0) or it does not have a numeric value, tracing is disabled.

To output a message to the log file, create and then initialize an instance of the JadeLog class. You must specify a file name in the fileName property, and you can set other logging options. For details, see "JadeLog Class Properties", later in this section. To output log messages, send messages with the message binary or text to the log object by using the log, info, or trace methods or one of the methods whose name starts with log, info, or trace (for example, logServer, infoClient, or traceDumpClient).

Messages sent in the log and info methods are always output. The file buffer is flushed when a message is output with the log method and it is buffered when it is output using the info or trace methods. (The output of a message with the trace method is determined by the setting of the <selector-name> parameter in the [JadeLog] section of the JADE initialization file having a non-zero value and the same name as the selector property value.)

As a lot of calls to log APIs increases the amount of physical disk IO, where possible use the info methods to avoid impacting on the performance of the application.

The JadeLog class supports log messages and informational (status) messages.

The file buffer is flushed when a log message is output, ensuring that the message is written to the file. The file size is checked at the same time to see if a new log file is required. As neither of these actions occurs when an informational message is logged, the file buffer is flushed by the operating system and no check is performed on the file size. Although you can output a log message to force the file size to be checked, this operation is more expensive than letting the operating system flush the buffer by checking the file size periodically when logging informational messages.

The JadeLog class destructor method closes the log file. When multiple instances of the JadeLog class use the same file, the log file is closed when all instances have been deleted.

If the value of the filePath property is null and the fileName property does not contain a path, log files are output to the directory specified by the LogDirectory parameter in the [JadeLog] section of the JADE initialization file.

If a file is versioned (the default) when the size of the file reaches the value specified in the maxFileSize property, a new file is created with the next available version number; for example, mymsg1.log is followed by mymsg2.log, and so on. If the maxFileSize property is set to zero (0), the value of the MaxLogFileSize parameter in the [JadeLog] section of the JADE initialization file is used.

The following example shows the use of properties and methods defined in the JadeLog class.

vars
    myLog : JadeLog;
begin
    create myLog;
    // Tracing will be output if the value of MyLogging is
    // non-zero in the [JadeLog] section of the Jade.ini file
    myLog.selector := 'MyLogging';
    // Output is to MyLog[n].log in the default log directory
    myLog.fileName := 'MyLog';
    // Log files are versioned at 10MB
    myLog.maxFileSize := 10000000;
    // Log a start-up (informational) message - do not flush the file
    myLog.info('starting up');
    // Log a message on the server - do not flush the file
    myLog.infoServer('tracing about to start on a client');
    // The following message is output only if MyLogging is
    // non-zero in the Jade.ini file
    myLog.trace('start time: ' & app.actualTime.String);
epilog
    // Unconditionally output a message - flush the file
    myLog.log('all done');
    // Deleting the log instance will close the log file
    delete myLog;
end;

For details about the properties and methods defined in the JadeLog class, see "JadeLog Class Properties" and "JadeLog Class Methods", in the following subsections.

Object

(None)