BOOL PBInitialize ()

Return value

Returns TRUE if initialization succeeds (or has already succeeded on a previous call) else FALSE. Note that a return of FALSE may only indicate that Paul Bunyan is not installed on the machine.


This function is executed automatically the first time a process calls any API function that requires initialization, so it is not necessary to call it. It is provided only as a diagnostic and for people who have extremely high performance requirements. The only advantage in explicit initialization is a very slight speed gain the first time a process logs since the implicit initialization that normally would be done on the first call will already have been done.

The Paul Bunyan library uses numerous global variables. These variables are initialized once for each process using the library. When linked into a dynamic link library, the global variables are always placed in a per-process data segment, meaning each process that loads the DLL will get a separate copy of the globals. Initialization is performed once for each process that uses Paul Bunyan functions from the DLL. This is true even if the DLL uses a shared data segment. The library uses handles to kernel objects that must be initialized per process per module, so we make sure our data will not be linked into a shared data segment.

If library initialization fails, an error message will be placed in the application event log, and all subsequent calls to logging functions will return immediately. The only exception is when the message server has not been installed. In this case, library initialization will deliberately fail without generating any kind of error message. This allows code built with the library to be run on a machine that does not have Paul Bunyan installed without any penalty. It may be possible for an incomplete or improper installation to cause logging to fail silently, but the message server will always generate an event log error message if it fails to load. Thus an improper installation can be distinguished from no installation at all.

The command line and COM interfaces ultimately use the same library as the C/C++ API, so the same considerations apply to them.