$PUTMESS_LOG_FILE

Copy the message frame contents to one or more files.

$PUTMESS_LOG_FILE | $PUTMESS_LOGFILE {=} Filename | {/append}

$PUTMESS_LOG_FILE | $PUTMESS_LOGFILE {=} Filename {, totalsize=n} {, count=p}

$PUTMESS_LOG_FILE | $PUTMESS_LOGFILE {=} NONE

Arguments

Argument Meaning
Filename Full path name to the output log file; can have a maximum length of 64 characters. The name can include one or more of the following identifiers, in any order, to differentiate individual log files.
  • %p—process ID of the started application. If specified, /append is ignored.
  • %t—time stamp. Using this adds an extra performance penalty, because the file names must also be saved.
  • %h—host name
  • %u—user name
  • %j—job number. If specified, /append is ignored. (iSeries only)
totalsize=n Total disk space in kilobytes that can be used for all rotating log files together. This size will not be exceeded. If not specified, the default value is 10000 (10 MB).
count=p Number of files used in rotating log files.

The minimum value of count is 2. There is no maximum. However, there is a lower limit to the log file size of 3 KB. If the combination of totalsize and count produce a file size that is less than that, the count will be reduced to achieve the minimum file size.

Note:  Rotating through a large number of files imposes a large overhead and performance penalty.
/append Append any message frame information to the specified Filename.
NONE Do not create log files for Uniface Router or Uniface Server processes. If specified, use uppercase. (Do not use quotes to specify an empty string. This will result in a log file)

Defaults

Assignment file: Any application assignment file
Section: [SETTINGS]
Default value: None

Description

Note:  It is recommended that you use $PUTMESS_LOG_FILE only during development and testing. Using it in a production environment can result in many large log files that use up valuable disk resources.

$PUTMESS_LOG_FILE directs a copy of the message frame information for the application to a log file Filename. The file contains a complete record of all output to the message frame, that is, the file is not cleared when the message frame is cleared. This means the log file can become very large if a large application is run. To control this, consider using rotating log files.

When a new file is created, a file banner is written to the file with information about the application. For rotating log files each banner line starts with the [logsegmentN]. For non-rotating files, the banner starts with [startup].

If the Filename already exists when the application starts using $PUTMESS_LOG_FILE, the file's contents are cleared, unless /append is used, in which case the logging information is added to the file.

If an application is started with /pri=64 (or higher), messages that occur before the assignment file is read are logged in the application's default assignment file. If no fatal errors are encountered, the log file and message level are reset to the values specified by $PUTMESS_LOG_FILE and $IOPRINT in the assignment file (if they are present), and the default log file is closed.

Rotating Log Files

Adding the optional totalsize=n and count=p parameters enables you to use rotating log files. The first and most recent file always has the name specified in the assignment setting.

When the file size reaches the maximum size, as determined by the totalsize divided by the count, the file is renamed, appending _1, and logging continues in a newly created file with the name specified in the assignment. When this file reaches the specified maximum size, the _1 file is renamed to _2, and the new file has _1 appended, and logging continues in a newly created file. This process is repeated until the number of log files matches the value of count, and then the oldest is deleted as new log files are created. As files are renamed, any existing file with that name is deleted.

As the log proceeds through the rotation, the oldest part of the log is deleted. Make sure you have defined a totalsize large enough to maintain a reasonable history, otherwise error messages written earlier may be lost.

If an error occurs during the rotation and it is no longer possible to guarantee that the total file size is below the totalsize argument, logging will stop. The error will be written to a uniface_app_type_%p.log in the working directory of the application, not in the directory specified for the $PUTMESS_LOG_FILE.

Using /append

You can use /append for rotating files to continue the rotation. If files exist with the same name and sequence numbers they will continue to be used.

Note: Never share rotating log files over multiple concurrent sessions. The size calculations will not be accurate.

For non-rotating log files, /append can be useful when two sessions are started, either simultaneously or sequentially. The file will contain the logging information from both sessions.

If /append is not defined, the file will contain only the logging information of the last session.

Log Files for Server Processes

For the Uniface Router or Uniface Server, there can be multiple server processes running concurrently. When $PUTMESS_LOG_FILE is not specified, the log file will be put in the working directory of the process, and have a name that reflects the application name and process ID, for example urouter02093.log or userver01234.log.

Normally, the default log file is created only if there is something to log, that is, if an error occurs or if $ioprint is greater than 0. To prevent the default log file from being created at all, set $PUTMESS_LOG_FILE to NONE in the server's assignment file. This will only take effect after the assignment file has been read. Thus, for the Uniface Router and shared servers, you need to restart the Uniface Router; for client applications and exclusive servers you need to restart the relevant client application.

When troubleshooting Uniface Routers and Uniface Servers, it can be useful to start them with /pri=64 (or higher). This ensures that assignment file or network errors, which can occur after the application has been started but before the assignment file is read, are logged. If no fatal errors are encountered, the log file and message level are reset to the values specified by $PUTMESS_LOG_FILE and $IOPRINT in the assignment file (if they are present). If $PUTMESS_LOG_FILE is specified, the default log file is closed and the specified log file is then used. Otherwise the default log file continues to be used.

Example: Setting $PUTMESS_LOG_FILE

In this example, if 214 were the process ID of the running application, the log file name would be named myapp214.log. 

[SETTINGS]
$PUTMESS_LOG_FILE=myapp%p.log

Related Topics