Section 3c - C Functions

ATMI C Function Reference

userlog(3c)

Name

userlog()—Writes a message to the BEA Tuxedo ATMI system central event log.

Synopsis

#include "userlog.h" 
extern char *proc_name; 
 
int userlog (format [ ,arg] . . .) 
char *format;

Description

userlog() accepts a printf(3S) style format specification, with a fixed output file—the BEA Tuxedo ATMI system central event log.

The central event log is an ordinary UNIX file whose pathname is composed as follows: If the shell variable ULOGPFX is set, its value is used as the prefix for the filename. If ULOGPFX is not set, ULOG is used. The prefix is determined the first time userlog() is called. Each time userlog() is called the date is determined, and the month, day, and year are concatenated to the prefix as mmddyy to set the name for the file. The first time a process writes to the user log, it first writes an additional message indicating the associated BEA Tuxedo ATMI system version.

The message is then appended to the file. With this scheme, processes that call userlog() on successive days will write into different files.

Messages are appended to the log file with a tag made up of the time (hhmmss), system name, process name, and process ID, thread ID, and context ID of the calling process. The tag is terminated with a colon (:). The name of the process is taken from the pathname of the external variable proc_name. If proc_name has value NULL, the printed name is set to ?proc.

BEA Tuxedo ATMI system-generated error messages in the log file are prefixed by a unique identification string of the form:

<catalog>:number>:

This string gives the name of the internationalized catalog containing the message string, plus the message number. By convention, BEA Tuxedo ATMI system-generated error messages are used only once, so the string uniquely identifies a location in the source code.

If the last character of the format specification is not a newline character, userlog() appends one.

If the first character of the shell variable ULOGDEBUG is 1 or y, the message sent to userlog() is also written to the standard error of the calling process, using the fprintf(3S) function.

userlog() is used by the BEA Tuxedo ATMI system to record a variety of events.

The userlog mechanism is entirely independent of any database transaction logging mechanism.

A thread in a multithreaded application may issue a call to userlog() while running in any context state, including TPINVALIDCONTEXT.

Environment Variables

ULOGMILLISEC

An on/off switch environment variable that time stamps messages sent to the userlog file in millisecond time intervals instead of seconds. If not specified, default time stamping is in seconds. The server must be rebooted when ULOGMILLISEC is turned on or off.
Example: ULOGMILLISEC=Y

ULOGRTNSIZE

An on/off switch environment variable that specifies the userlog rotation file size. The default rotation file size is 2GB. The server must be rebooted when ULOGRTNSIZE is turned on or off.
Example: ULOGRTNSIZE=1000000 (when the file size is 1Mb)

Rotated files are saved in using the following syntax: filename.nn.
Example: ULOG.083103.1, ULOG.083103.2 ... ULOG.083103.10, etc.

Note: If ULOGRTNSIZE is not specified, file rotation does not take place.

Portability

The userlog() interface is supported on UNIX and MS-DOS operating systems. The system name produced as part of the log message is not available on MS-DOS systems; therefore, the value PC is used as the system name for MS-DOS systems.

Examples

If the variable ULOGPFX is set to /application/logs/log and if the first call to userlog() occurred on 9/7/90, the log file created is named /application/logs/log.090790. If the call:

userlog("UNKNOWN USER '%s' (UID=%d)", usrname, UID);

is made at 4:22:14pm on the UNIX system file named m1 by the sec program, whose process-id is 23431, and the variable usrname contains the string "sxx", and the variable UID contains the integer 123, the following line appears in the log file:

162214.m1!sec.23431: UNKNOWN USER 'sxx' (UID=123)

If the message is sent to the central event log while the process is in transaction mode, the user log entry has additional components in the tag. These components consist of the literal gtrid followed by three long hexadecimal integers. The integers uniquely identify the global transaction and make up what is referred to as the global transaction identifier. This identifier is used mainly for administrative purposes, but it does make an appearance in the tag that prefixes the messages in the central event log. If the foregoing message is written to the central event log in transaction mode, the resulting log entry will look like this:

162214.logsys!security.23431: gtrid x2 x24e1b803 x239: UNKNOWN USER 'sxx' (UID=123)

If the shell variable ULOGDEBUG has a value of y, the log message is also written to the standard error of the program named security.

Errors

userlog() hangs if the message sent to it is larger than BUFSIZ as defined in stdio.h

Diagnostics

userlog() returns the number of characters output, or a negative value if an output error was encountered. Output errors include the inability to open, or write to the current log file. Inability to write to the standard error, when ULOGDEBUG is set, is not considered an error.

Notices

It is recommended that applications' use of userlog() messages be limited to messages that can be used to help debug application errors; flooding the log with incidental information can make it hard to spot actual errors.