Adiscon
ActiveLogger
User Manual

Version 1.2
2002-01-29

Table of Contents

1. Introducing Adiscon ActiveLogger
   1. Features
   2. Components
   3. System Requirements
2. Installation
3. Using ActiveLogger
   1. An ASP sample
   2. Interface description
4. The ActiveLogger Client
   1. Launching the Client
   2. The "Test Installation" Tab
   3. The Defaults Tab
   4. The License Tab
   5. The Menu
5. Troubleshooting
   1. Getting Help
   2. Product Updates
   3. Frequently asked questions
6. Version History
7. Purchasing ActiveLogger
   1. The License
   2. Pricing
   3. How to Order
8. Miscellaneous

Introducing Adiscon ActiveLogger

Adiscon ActiveLogger is an easy to use component to log messages to the Windows NT / 2000 Event Log and / or a syslog daemon (most often found under Unix). It is a standard component designed to work with Microsoft Active Server Pages (ASP) and other COM-enabled languages. This includes support for Windows Scripting Host (WSH) which makes it a very valuable tool in reporting any conditions occurring in automated scripts.

ActiveLogger is being used both by Administrators automating routine tasks as well as web developers.

We hope you find ActiveLogger as useful and easy to use as many others have found it. If you would like to contact Adiscon, please direct technical questions to support@adiscon.com. All other questions should be addressed to info@adiscon.com. 

Features

• Writes to Windows NT / 2000 Event Log

The Event Log is the standard event reporting mechanism under Windows. Utilize it's power with ActiveLogger for your own events.

• Syslog support

Under Unix and Linux, syslog is the standard event reporting mechanism. Send syslog messages to your central syslog server and thus have them included in a central alerting system.

• Ease of Use

ActiveLogger is extremely easy to use. Very few lines of code are required.

• Full Control over Logging Properties

Have full control over which syslog priority and facility is used. When logging to the event log, use any event type, ID and source. Writes also to the system event log.

• Centralized Configuration

The system administrator can setup ActiveLogger with the default properties to use.

• Very affordably priced

Adiscon ActiveLogger is licensed on a per machine basis. Thus, there is only one license needed per server using ActiveLogger - no matter how many clients connect to this server.

• Robustness

ActiveLogger is written to perform robust even under unusual circumstances.

Components

ActiveLogger Client

The ActiveLogger Client is used to configure all components and features of ActiveLogger.

ActiveLogger COM Control

The ActiveLogger COM control is the part actually used with Active Server Pages (ASP). It is a standard server-side ActiveX control. Besides ASP, it can be used with any COM-compliant language, e.g. Windows Scripting Host, Visual Basic, Visual C++ or Delphi.

System Requirements

ActiveLogger has minimal requirements. Roughly 6 MB of disk space are needed. The product works with current versions of Windows NT 4 and 2000. Syslog delivery is supported under Windows 9x and Millennium Edition (NT event logging is obviously not available on these operating systems).

Installation

Installation is quick and easy. 

The install set (the ZIP file you downloaded) contains a standard setup program and it's necessary helper files. If you didn't receive a self extracting exe file, please unzip the archive to any directory you like. This can be a local drive, a removable one or a remote share on a file server. A Win32 Unzip program can be found at http://www.winzip.com.

After unzipping, simply double-click "setup.exe" and follow the onscreen instructions.

Setup.exe will install ActiveLogger.

By default, the download set is offered as a self-extracting exe file. It will also start the setup program right after decompressing the files.

Using ActiveLogger

Adiscon ActiveLogger is extremely easy to use. It requires just 2 lines of code to check a credit card number.

An ASP Sample

The following 2 lines of code are needed:

set oActiveLogger = CreateObject("Adiscon.ActiveLogger")
call oActiveLogger.LogToSyslog("My Message to be logged")

The ActiveLogger Interface

This chapter details how ActiveLogger can be used. Being a standard Windows component, it has a set of properties and methods.

Properties

• SyslogFacility
• SyslogPriority
• SyslogPort
• SyslogServer
• EventLogComputer
• EventLogSource
• EventLogType
• EventLogID
• MessageToLog

SyslogFacility

Type: Integer

Facility to use when reporting to syslog server. This value is only used if no user-defined priority is set via the respective property. Valid numerical values are:

Please note: the mnemonic constants given in the above table are only available with environments / languages that support reading of type libraries. ASP does not allow this, so the numerical values need to be used.

Values in the range from 10 to 15 are not defined in the syslog protocol. You can use these values if your syslog daemon does support them. If you are not sure about this, we strongly recommend not using these values.

The default facility used is alLOG_LOCAL0. We recommend using the alLOG_LOCALx facilities only. 

SyslogPriority

Type: Integer

Priority to be used when reporting syslog messages. This value is only used if no user-defined priority is set via the respective property. Valid numerical values are:

Please note: the mnemonic constants given in the above table are only available with environments / languages that support reading of type libraries. ASP does not allow this, so the numerical values need to be used.

It is highly recommended that applications do not use the emergency priority (alLOG_EMERG) unless absolutely necessary.

SyslogPort

Type: Integer

Port to be used to connect to the syslog server. If set to 0, ActiveLogger is instructed to use the system services database to find the default syslog port (514 if left untouched). The default value is 0. Other values are typically used to allow delivery to syslog daemons behind a firewall.

SyslogServer

Type: String

Syslog server (daemon) to report the message to. Can be either an IP address or an resolvable host name.

The default value for this property is "127.0.0.1" (the local machine). This most probably is not the machine that should receive the syslog message. So this property must be set. Alternatively, your server administrator can set a default syslog server via the ActiveLogger client. In this case, the property does not need to be set. Please consult you administrator if a proper default has been set.

EventLogComputer

Type: String

ActiveLogger can log to the event log of any computer the current user (process) has permissions to. This property specifies the computer name. Please use the NETBIOS name of the system to log to (e. g. "MYSERVER"). If left blank, logging is to the local machine.

Please note that logging to the system log on a remote machine is only possible if Adiscon ActiveLogger is installed on that remote machine. Otherwise, these messages will be written to the application log.

EventLogSource

Type: String

The source to be used when logging to the event log. The default value is "Adiscon ActiveLogger". You can change that source name, however, we do not recommend that. There are two reasons for this: first of all, your source name might conflict with another source already installed in the system. This can lead to confusing situations. Secondly, if the source name is not defined in the system, event viewer will display a warning message together with your logged text. This in no way limits the logging functionality, but might also be confusing to some users.

The source name also specifies in which log part (application or system) entries are made. If you would like to log to the system log, the source name must be "Adiscon ActiveLogger SYSTEM-Log". Logging to the system log with custom defined source names is not possible. Also, please note that ActiveLogger must be installed on each system where system log entries shall be written (otherwise the "Adiscon ActiveLogger SYSTEM-Log" source will also write into the application log).

EventLogID

Type: Integer

Event ID to be used. This is a user-definable value. From the operating system point of view, this value is irrelevant. However, it can be used by filters and monitors (like NT event viewer or Adiscon EventReporter) to group and/or filter events.

Adiscon recommends using event IDs 0 to 50, only. ActiveLogger has defined so-called message library entries for these events. This ensure smooth display of the message in NT event viewer and other tools. If you select any other value, no message library entry is available which leads to a warning message being generated. The actual log entry is fully valid, but the message might cause some confusion.

EventLogType

Type: Integer

Type to be used when reporting events. Can be one of the following values:

Please note: the mnemonic constants given in the above table are only available with environments / languages that support reading of type libraries. ASP does not allow this, so the numerical values need to be used.

The default type is alEVENTLOG_INFORMATION_TYPE. The setting of this property should reflect the severity of the event.

MessageToLog

Type: String

This is the message to be logged to either the syslog daemon or the event log (depending on method call). It serves as an alternate way to provide the message - it can also be specified directly when calling the respective method. We recommend specifying the message directly with the method call (its faster).

Methods

• LogToSyslog
• LogToEventLog

LogToSyslog

Interface: LogToSyslog(Message)

Parameters:

• Message
  This is the message to log. If null or blank, property "MessageToLog" is used instead.

This method actually writes the syslog message. It evaluates all other properties (e. g. SyslogPriority, SyslogServer) and constructs the message according to their values. Then it sends it via syslog protocol. If a blank Message is given with the method call, property "MessageToLog" is evaluated and used as message text. Otherwise, "MessageToLog" is ignored.

LogToEventlog

Interface: LogToEventlog(Message)

Parameters:

• Message
  This is the message to log. If null or blank, property "MessageToLog" is used instead.

This method actually writes the message to the Windows NT / 2000 event log. It evaluates all other properties (e. g. EventLogID, EventLogType) and constructs the message accordingly to their values. If a blank Message is given with the method call, property "MessageToLog" is evaluated and used as message text. Otherwise, "MessageToLog" is ignored.

The ActiveLogger Client

The ActiveLogger Client is used to customize the product.

The client loads the configuration parameters upon startup. Modifications are saved by clicking the "OK" button. Clicking the "Cancel" button will close the ActiveLogger Client without saving any modifications.

Launching the ActiveLogger Client

To run the ActiveLogger Client, click the "ActiveLogger Client" icon present in the ActiveLogger program folder located in the Start menu.

The ActiveLogger Client can also be launched from the command prompt:

1. Open a Command Prompt window
2. Change to the drive and directory where the ActiveLogger software is installed (default: "\Program Files\ActiveLogger")
3. Type "activelogger.exe" and hit enter.

The "Test Installation" Tab

This tab is used to test the successful installation of ActiveLogger. It can also be used to log messages to interactively.

ActiveLogger Client - Test Installation Tab

The "Defaults" Tab

This tab is used to configure default values to use with ActiveLogger. If defaults are enabled, they are loaded into ActiveLogger's properties when the control is instantiated. The user can change any of these properties.

ActiveLogger Client - Defaults Tab

• Enable Defaults

Check this box, to enable default processing. If left unchecked, no defaults will be read upon control instantiation. Disabled defaults are used in very demanding environments to achieve the highest possible throughput. The performance gain is minimal, but might be worth it.

For normal operation, we recommend enabling defaults.

• Server

The name or IP address of the syslog server (daemon) to log to. If in doubt, please contact your system administrator to obtain this value.

• Facility

The facility to be used when logging the syslog message. The facility used should correspond to your syslog daemon's setup. By default, the LOCAL_0 facility is used. This default should be OK for the standard syslog daemon setup. Please consult your syslog administrator for details on how to set this value. 

Please note that it is possible to use the system facilities. However, Adiscon recommends using the LOCAL_0 to LOCAL_7 facilities only. 

• Priority

The priority used to log the syslog message. This value usually corresponds to some kind of processing at the syslog daemon's side. We recommend not using the "Emergency" priority. In any case, it is a good idea to talk to your syslog administrator about the priority to use.

• Port

The port the syslog daemon is listening on. This property can be any valid IP port or the value 0. If 0 is selected, the actual port is obtained from the system services database (which is usally 514). We recommend setting this value to 0 unless definitely needed.

Changing the port is most common in environments that contain firewalls.

• Computer to Log to

ActiveLogger can log to the event log of any computer the current user (process) has permissions to. This property here specifies the computer name. Please use the NETBIOS name of the system to log to. If left blank, logging is to the local machine.

Please note that logging to the system log on a remote machine is only possible if Adiscon ActiveLogger is installed on that remote machine. 

• Source

The source to be used when logging to the event log. The default value is "Adiscon ActiveLogger". You can change that source name, however, we do not recommend that. There are two reasons for this: first of all, your source name might conflict with another source already installed in the system. This can lead to confusing situations. Secondly, if the source name is not defined in the system, event viewer  will display a warning message together with your logged text. This in no way limits the logging functionality, but might also be confusing to some users.

The source name also specifies in which log part (application or system) entries are made. If you would like to log to the system log, the source name must be "Adiscon ActiveLogger SYSTEM-Log". Logging to the system log with custom defined source names is not possible. Also, please note that ActiveLogger must be installed on each system where system log entries shall be written (otherwise the "Adiscon ActiveLogger SYSTEM-Log" source will also write into the application log).

• Type

Log entry type. This should reflect the severity of the event. 

• ID

Event ID to be used. This is a user-definable value. From the operating system point of view, this value is irrelevant. However, it can be used by filters and monitors (like NT event viewer or Adiscon EventReporter) to group and/or filter events.

Adiscon recommends using event IDs 0 to 50, only. ActiveLogger has defined so-called message library entries for these events. This ensure smooth display of the message in NT event viewer and other tools. If you select any other value, no message library entry is available which leads to a warning message being generated. The actual log entry is fully valid, but the message might cause some confusion.

The License Tab

The license tab is used to activate your ActiveLogger installation after activation.

After evaluation, ActiveLogger can be activated just by entering a correct registration name and number. There is no need to reinstall. The activation information is provided by Adiscon after purchasing.

Please note: the ActiveLogger Client can not verify the correctness of  the registration information. So it will accept any combination without complaint. However, if the information is incorrect, the ActiveLogger service will not switch into active state. For this reason, it will continue to report that it is unregistered. If you have purchased ActiveLogger licenses and are unable to turn off the services' registration reminder, you should check the exact registration information entered. There most probably is a typo in it.

ActiveLogger Client - License Tab

• Registration Name

The registration name is chosen by you. It should correspond to your organization name, e.g. a company called "AA Carpenters, Inc." should not chose "AA" as registration name. This can easily be mistaken and most probably will be rejected by Adiscon for that reason. With the above scenario, we recommend using the full company name "AA Carpenters, Inc.".

Please note: the registration name is case sensitive. It must be entered exactly as given. Leading and trailing spaces are also part of the registration name, so be sure to enter none.

• Registration Number

This number is provided by Adiscon. It is valid for a specific registration name. Be sure to enter the correct registration number. The ActiveLogger Client is unable to detect invalid registration numbers and as such can not detect any typos.

The Menu

The menu bar offers some basic functions.

The menu offers also a dialog to check the ActiveLogger version numbers. Please select "Help"/"About" to receive the "About" dialog shown below. The "About" dialog displays the ActiveLogger version number as well as the version and build ID of the ActiveLogger client.

Troubleshooting

Getting Help

Do you need help with ActiveLogger or need an important question answered? No problem, there is lots of help available!

Please note that all options (except priority support) are also open to evaluating customers. So do not hesitate to try them. Help is available in English and German language. Our local resellers may provide local language support. Please check with them.

• ActiveLogger Web Site

Visit the support area at http://www.ActiveLogger.com/en/support for further information. If for any reason that URL will ever become invalid, please visit http://www.adiscon.com for general information. 

• Support Newsgroups

Share questions and answers with your peers! These groups are also monitored by Adiscon support staff.

NNTP (Newsreader)

news://news.adiscon.com/adiscon.products.ActiveLogger

• Email

support@adiscon.com - an appropriate subject line is highly appreciated

• Phone

+49-2235-985004   (with "+" being the international dialing prefix, e.g. 011 in the US)

Please note that we are in the Central European Time zone (CET). That is 1 hour east of Greenwich. If it is 12pm in New York, it is 18pm at our office location. Our office hours are from 9am to 4pm. So we generally advise US customers to call in early mornings and Asian customers to call in late afternoon.

For best customer service, highly recommend limiting phone calls to emergencies. We are checking our other support options regularly.  

• Fax

+49-2235-985032   (with "+" being the international dialing prefix, e.g. 011 in the US)

• Software Maintenance

Software maintenance including priority support is available for an annual fee of 20% of the product purchase price. If you are interested in this option, please contact us at info@adiscon.com.

• Non-Technical Questions

info@adiscon.com

This email alias will answer all non-technical questions like pricing, licensing or volume orders (51 licenses and up). 

Product Updates

ActiveLogger is being developed since 2000. New versions and enhancements are being made available continuously.

Please visit http://www.ActiveLogger.com for information about new and updated products. Registered users will receive notification of new versions via email.

Frequently asked Questions

For a current list of Frequently Asked Questions (FAQ), please visit http://www.ActiveLogger.com/en/FAQ.

Registry Keys

This section is a reference on registry keys used by the application. This information is included for administrators who would like to have complete information on the application details, e.g. to utilize a mass rollout. A typical user can simply ignore this chapter, as it contains no information relevant to operate the product.

szLicensee

Type: string value

This is the name of the licensed user. The trial version does not have a licensee name string. It specifies "unregistered". If you register your copy of EventReporter, you specify the license string of your choice. If it is not already used by another user, you will receive a matching license number (next parameter, nLicenseKey) from Adiscon. Enter both the license name and key into the registry. This will turn off the trial version warning. If it doesn't turn them off, be sure to check if both the name and number are correctly entered.

Please note that this parameter is case-sensitive!

nLicenseKey

Type: DWORD value.

This is the license key issued by Adiscon. It must match the license name (szLicensee, see directly above). If it does not match, the EventReporter service will not recognize your installation as licensed.

bBootFromRegistry

Type: DWORD value.

If set to 1, the configuration defaults are read from registry. If set to 0, registry information is ignored. Set this parameter to 0 in a high volume environment to achieve highest throughput.

The defaults set in the ActiveLogger client are only active if bBootFromRegistry is set to 1.

iSyslogFacility

Type: DWORD value.

Facility to use when reporting to syslog server. This value is only used if no user-defined priority is set via the respective property. Valid numerical values are:

Values in the range from 10 to 15 are not defined in the syslog protocol. You can use these values if your syslog daemon does support them. If you are not sure about this, we strongly recommend not using these values.

The default facility used is LOG_LOCAL0. We recommend using the LOG_LOCALx facilities only.

This is the initial value after instantiating the COM control. It can be overridden by client properties.

iSyslogPriority

Type: DWORD value.

Priority to be used when reporting syslog messages. This value is only used if no user-defined priority is set via the respective property. Valid numerical values are:

It is highly recommended that applications do not use the emergency priority unless absolutely necessary.

This is the initial value after instantiating the COM control. It can be overridden by client properties.

iSyslogPort

Type: DWORD value.

Port to be used to connect to the syslog server. If set to 0, ActiveLogger is instructed to use the system services database to find the default syslog port (514 if left untouched). The default value is 0. Other values are typically used to allow delivery to syslog daemons behind a firewall.

This is the initial value after instantiating the COM control. It can be overridden by client properties.

szSyslogServer

Type: string value.

Default syslog server (daemon)  to use when no one has been specified.

This is the initial value after instantiating the COM control. It can be overridden by client properties.

szEventLogComputer

Type: string value.

Default computer to use for NT event logging. Events reported via LogToEventLog() will be written to that computer's event log. If left unspecified, the local machine will be used (default).  

This is the initial value after instantiating the COM control. It can be overridden by client properties.

szEventLogSource

Type: string value.

Source to use for when logging the Event. Can be any valid string value. The default value is "Adiscon ActiveLogger". 

This is the initial value after instantiating the COM control. It can be overridden by client properties.

iEventLogID

Type: DWORD value.

Source to use for when logging the Event. Can be any valid value. We recommend limiting this to values 0 to 50 because these EventIDs are well defined inside the product and thus display neatly in event viewer. The default value is 0. 

This is the initial value after instantiating the COM control. It can be overridden by client properties.

iEventLogType

Type: DWORD value.

Type to be used when reporting events. Can be one of the following values:

The default type is alEVENTLOG_INFORMATION_TYPE.

This is the initial value after instantiating the COM control. It can be overridden by client properties.

Version History

This short history shall provide you with some background information about the versions available as well as their pros and cons.

This is user driven software. Please provide us with your feedback. Many features have become reality with the help of envisioning users!

1.0

Released 2001-02-01.

• This is the initial release.

1.1

Released 2001-06-08

• Fixed a bug that caused ActiveLogger to expire when using a licensed version.
• Reduced the ActiveLogger dll size.

1.2

Released 2002-01-29

• Enhanced the ActiveLogger Client to generate a VBScripts out of the Test Installation values.
• Removed minor bugs in the ActiveLogger Client. 

Purchasing ActiveLogger

The License

ActiveLogger is distributed as Shareware. You are free to use the product for evaluation. However, if you feel comfortable with it and plan to use it for an extended period of time, you must register with Adiscon and pay the license fee. A license is needed for any system the ActiveLogger service is running on. It does not matter if the operating system is a workstation or server version.

Please support further development by registering the product. There is a license fee per system the ActiveLogger component is installed on. 

BBS sysops feel free to include the distribution set of this product in your library. Please be sure to include the full set (program & this documentation). Any questions can be directed at info@Adiscon.com.

Liability

Please use the evaluation period to check if ActiveLogger is suitable for you and your system environment. We encourage you to try ActiveLogger in a test environment. We accept no liability for any damage during the evaluation period.

Liability for registered users is limited to the amount of the registration fee.

Are there any restrictions in the unregistered trial version?

No, the version is fully functional for 30 days. After that time, it stops working and always logs the message "unregistered product expired - please register at http://www.ActiveLogger.com". The unregistered version also indicates its status by applying a respective message to the messages being logged.

Pricing

For orders outside of the "Euro-Zone" (European countries that have the Euro currency), the fee is $US 19 (plus tax if applicable). Euro-Zone orders are EURO 25,-- including 16% VAT. European Community residents with VAT identification number should state this number in order to receive tax exemption. If not stated, full VAT will be charged. All EU orders will be processed in Euro. US$ payment is available for international customers, only.

Please call for volume orders (info@adiscon.com).

How to order

Most convenient way - order online: https://secure.adiscon.com/Shop/en/ActiveLogger.asp.

If you do not like to order only, registration is still as simple as 1-2-3:

1. Print out the following registration form
2. Please fill it in. Remember to include number of licenses requested and payment information as well as your email id.
3. Mail or fax the registration form to Adiscon.

We accept cash (bills please – and: no faxed ones, please ;-) ) as well as all major credit cards. We also accept payment by check if - and only if - the following criteria is met:

If you are paying in US$, your check must be drawn on an US American bank and made payable to "Rainer Gerhards" (very important, do not make payable to Adiscon GmbH!). International money transfer is available upon request for reasonable high amounts.

If you need any additional payment options, please contact us at info@Adiscon.com or the below given addresses.

Direct your orders to:

Adiscon GmbH
Franz-Marc-Strasse 144
50374 Erftstadt
Germany

Fax: +49-9349-928820
email: order@Adiscon.com
Web: http://www.ActiveLogger.com (follow order link)

Order Form

Your order can be placed using the following form. And - yes, you can order directly from the manual! All you need is a working Internet connection. Fill in the fields and press "Order!". This will create a transaction in Adiscon's secure order processing system. Your data is encrypted using SSL.

The most current online order form is available at https://secure.adiscon.com/ActiveLogger/en/.

If you'd like to order by mail or fax, please print out the order form and sign it.

ActiveLogger Order Form

Please sign:

________________________________________________________
Date & Signature

and forward this form to

Adiscon GmbH
Franz-Marc-Strasse 144
50374 Erftstadt
Germany

Fax: +49-2235-985032
Fax option for Credit Card orders, only.

Miscelleanous

Year 2000 Compliance Statement

ActiveLogger has been designed and implemented in the year 2000. As such, it is is Year 2000 compliant.

Note: This statement does not in any way guarantee that ActiveLogger will correctly operate across the Year 2000 boundary on any machine who’s BIOS and operating system is not Y2K compliant. Also please note that ActiveLogger forwards event log records written by a vast variety of products. We can not guarantee that all of this products are year 2000 compliant. ActiveLogger simply forwards what is written to the event log, so be sure to check with the other vendors.

Copyrights

This documentation as well as the actual ActiveLogger product is copyrighted by Adiscon GmbH, Germany.

Microsoft, Windows, Windows 2000 and Windows NT are registered trademarks of Microsoft Corp., Redmond, WA, USA. 

Other Products of Interest

You might be interested in Adiscon WinSyslog, a syslog server (daemon) for Windows. More Information on WinSyslog is available at http://www.winsyslog.com. An event log monitor that checks and forwards Windows event log information is available at http://www.eventreporter.com.