Output File 

Use

Directing messages into a file is a very common practice. In the SAP Logging API this is done by assigning FileLog to your source objects. This section explains certain common configuration features to complement the JavaDocs.

More information: Appendix C: Default Behavior of Certain Objects.

By default, messages written to an output file are in the ListFormatter format, without using any special character encoding. There is only one single output file that constantly increases in size. There are a number of options you can use to configure the behavior of an output file, using the SAP Logging API:

●      Filename

●      Limit file size and do sequencing on the output file

●      FileLog versus Physical file

Features

Filename

The filename can be expressed as a full file path or in a pattern with a number of available placeholders. This can help the potential “hardcoding” problem and platform dependent issues, such as the filename separator.

Placeholder

Placeholder	Description	Comments
/	Local file name separator.	“C:\temp\trace.log” == “C:/temp/trace.log”
%h	Home directory.	The value of the system property: ‘user.home’
%t	System temporary directory.	The value of the system property: ‘java.io.tmpdir’. Normally, it is “C:\temp”. Therefore:“C:\temp\trace.log” == “%t/trace.log”
%u	A number that makes the file name unique.	To avoid file naming conflicts.
%%	The percentage sign.
%g	The sequence number of the file.	This is useful only when you specify the file size limit and the maximum number count to do rotation. By default, this is appended to the end of the filename/file pattern specified. For example: “%t/trace.%g.log”  →  “C:\temp\trace.0.log”. By default: “C:\temp\trace.log.0”

Output File Sequence and Rotation

This is done implicitly when you specify values for the file size (in bytes) and the cap for the sequencing count, before rotating back to the first file. This pair of parameters must coexist together – either they both have values assigned, or both have values equal to zero. Otherwise, depending on the option you use to do the configuration, either an exception can be thrown (through the API), or “best guess” values are used (through the configuration file). For example, both attributes get default zero values.

More information: Administrative Issues.

This can be done when the FileLog constructor is called.

FileLog _file = new FileLog("%t/trace.%g.log", 800000, 10, new TraceFormatter());

In case of the configuration file, the syntax is:

log[File]                  = FileLog log[File].pattern          = %t/trace.%g.log log[File].limit            = 800000 log[File].cnt              = 10 log[File].formatter        = TraceFormatter

 

The first output file is created in the “C:\temp\trace.0.log” (sequence number starts with ’0’ ) and when its size exceeds the limit (800,000 bytes), the next incoming message will be directed to a new file – “C:\temp\trace.1.log”. This process continues until the last sequenced file “C:\temp\trace.9.log” (count = 10). Then the next file to be written will be again in “C:\temp\trace.0.log”.

FileLog vs Physical File

A FileLog is a logical representation of a physical output file where messages are directed. With the several configuration options mentioned in the previous section, you can manipulate the output behavior of the output file through the API of the FileLog. You can also do assignments of the FileLog to source objects.

1:1 Recommended

The FileLog and the actual output file must be in a 1:1 relationship.

It is not recommended that you create two instances of the FileLog on the same file with different configuration. For example, one with TraceFormatter and another with XMLFormatter. If you do so, you may not synchronize the messages in a multi-threading environment correctly. The full message text may be interrupted and interwoven with another message text.