INFO: Enabling detailed logging within Zetafax.
ID: ZTN1065
This Zetafax technical note applies to:
- Zetafax 8 and later.
Summary
Most Zetafax programs can be configured to produce their own detailed log files called "trace logs". These are intended to help technical support staff from Equisys and other companies to resolve related problems that may occur.
This document gives instructions for enabling detailed logging for server programs/devices when asked to do so by a technical support engineer - this produces a log file which can then be sent to the engineer for analysis.
Because of the amount of information logged it is helpful to keep it specific to the problem which is occurring, (e.g. if the problem occurs sending to a specific fax number, then after enabling the trace log you should restart the server, send a fax to that fax number, then stop the fax server again.)
The logs relate to the current run of the server only - they are deleted each time the Zetafax server is restarted. However they can become very large, and there is an overhead in producing them, so they should be switched off again by deleting the relative line in the configuration file once they are no longer required.
WARNING: Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Equisys cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.
Contents
Devices (e.g FAX and SMS modems and Intelligent fax cards)
Zetafax Printer and ZFDaemon on Windows 2000/2003 Terminal Services using the logging tool
Zetafax Client/Server installation
More information
Queue manager
The Zetafax Queue manager module QM.EXE may be configured to produce a detailed log file by following these instructions.
Edit the file zfax\SYSTEM\Z-DB\SETUP.INI (where 'zfax' is the name of the directory where the Zetafax files are installed). Locate the '[QUEUEMAN]' paragraph then add one of the following lines at the end of this section:
|
TraceLog: FULL |
Most complete level of logging. |
|
TraceLog: ON |
Reduced level of logging. |
Save the file, and then restart the Zetafax server.
Messages will now be written to ' zfax\SERVER\Z-DB\QM.LOG'.
LCR (Least cost routing)
The least cost routing module ROUTER.EXE may also be configured to produce a detailed log file by following the instructions below.
Edit the file zfax\SYSTEM\Z-DB\SETUP.INI (where 'zfax' is the name of the directory where the Zetafax files are installed). Locate the '[ROUTER]' paragraph then add one of the following lines at the end of this section:
|
TraceLog: FULL |
Most complete level of logging. |
|
TraceLog: ON |
Reduced level of logging. |
Save the file, and then restart the Zetafax server.
The messages are written to ' zfax\SERVER\Z-DB\ROUTER.LOG'.
Devices
All fax devices (modems, Gammafax, Brooktrout and CAPI devices) can be configured to produce a detailed log file by following these instructions.
For all the devices, logging is controlled by the 'TraceLog: FULL' line in the device's paragraph
e.g. [FCLASS-1] or BTB-G1 in ZETAFAX SERVER\SYSTEM\Z-DB\SETUP.INI (where 'Zetafax server' is the name of the directory where the Zetafax files are installed). This will generate a file with the device's name (e.g. FCLASS1.log, BTROUT1.log, BTB-G1-1.log etc) in Zetafax server\SERVER\Z-DB.
|
TraceLog: FULL |
Logs all messages, including those generated outside calls, and logs extra details (such as timing for DEVFC, and the original fax data file for DEVGF) |
Dynamic data exchange
This option is intended to help someone using DDE to ensure that it is being used correctly - if a problem is being experienced this will help both the user and technical support staff to identify where the problem is occurring.
DDE logging is an option of the Zetafax client, which enables large amounts of DDE tracking information to be written to the Zetafax client log file ZETAFAX.LOG.
To enable this option on version 8 or older systems you need to add:
|
DebugDDE: ON |
to the end of the [WORKSTATION] section of %windir%\ZETAFAX.INI.
DDE conversations will now be tracked in ZETAFAX.LOG. The LogArea: line in ZETAFAX.INI will determine the location of this file, but is typically either %windir% or the directory given by the TEMP/TMP environment variable (e.g. C:\TEMP or C:\WINDOWS\TEMP).
To enable this option on version 9 or later systems you need to add the same line in a different file at the end of the [WORKSTATION] section of C:\Documents and Settings\< UserName> \Application Data\Equisys\Zetafax Client\ZFCLIENT.INI.
DDE conversations in this case will now be tracked in ZETAFAX.LOG. The LogArea: line in ZETAFAX.INI will determine the location of this file, but is typically either %USER% or the directory given by the TEMP/TMP environment variable (e.g. C:\TEMP or C:\Documents and Settings\< UserName> \Local Settings\Temp).
This is the log file from a sample Word macro with Zetafax 6.01g. Although the logged information may be extended in future releases the general format is likely to remain the same:
99-11-04 17:01:48 FFFF -------------------- Zetafax program started
99-11-04 17:04:19 FFFF DDEServWndProc DDE Initiate (window 777804e2): app: " Zetafax" topic: " Addressing"
99-11-04 17:04:19 FFFF DDEServWndProc DDE Execute (window 777804e2): [DDEControl]
99-11-04 17:04:29 FFFF DDEServWndProc DDE Poke (window 777804e2): atom: TO, memory: 00ae0034
99-11-04 17:04:29 FFFF DDEServWndProc DDE Execute (window 777804e2): [Send][DDERelease]
99-11-04 17:04:29 FFFF DDEServWndProc DDE Terminate (window 777804e2)
99-11-04 17:05:52 0000 -------------------- Zetafax program ending
If there is an error you will get a line saying " returned error #" where the # symbol can be a number from 0 to 6.
The numbers mean:
|
0 |
No error |
|
|
1 |
Memory error |
(workstation out of memory?) |
|
2 |
Clipboard format not supported |
(only text is supported) |
|
3 |
Conversation not found |
(DDE conversation started without initialising it?) |
|
4 |
Topic not supported |
(DDE topic not supported/found) |
|
5 |
Atom error |
(problems with the atom table) |
|
6 |
Invalid Item |
(normally used after the user is told about the error via a dialog box) |
Zetafax API up to Version 8.01
To enable detailed logging of the Zetafax API you will need to add the following lines to the end of %windir%\ZETAFAX.INI file.
[API]
|
Trace: ON |
Logs all API calls except mail gateway |
API conversations will now be tracked in %windir%\ZFAPI.LOG
Note: These settings are only supported from version 6.01h or later.
Zetafax API Version 9 and later
To enable detailed logging of the Zetafax API you will need to add the following lines to the end of the \ProgramFiles\Zetafax server\ZETAFAX.INI file on the *server* pc.
[API]
|
Trace: ON |
Logs all API calls except mail gateway |
API conversations will now be tracked in the < loggedonuser> /docs and settings/local settings/temp area. It will be called ZFAPI.LOG
Zetafax e-mail gateway
The Zetafax e-mail gateway programs include a trace logging facility to log detailed information about their operation to a series of files. This is designed to assist technical support staff in identifying and resolving problems, which are reported from customer sites.
To create a trace log for the gateway, edit the file zfax\MAIL\DATA\DRIVER.INI (where 'zfax' is the name of the directory where the Zetafax server files are installed).
Add the following lines to the [GENERAL] section (modifying the line if present, or adding it if not)
[GENERAL]
debugdll=1
debug=1
Save the file, and then restart the Zetafax server. When faxes are sent through the gateway the following three text files, which will be written to the zfax\MAIL\DATA directory.
debugdll.txt
debugstf.txt
debugsm.txt
Some information may also be written to the WIN.INI file (found in the system root folder) under the following section.
[GWSTF]
On Microsoft Exchange systems, some information may also be written to the WIN.INI file (found in the system root folder) on the Exchange server which has the Zetafax Connector installed, under the following sections.
[IPM_IN]
[IPM_OUT]
Unless asked otherwise by technical support staff, after enabling the trace logging you should reproduce the problem which is occurring then send the 3 trace log files (*.TXT) together with WIN.INI from the Zetafax server and Zetafax Exchange Connector computers to the support engineer who has requested it.
Zetafax Printer and ZFDaemon on Windows 2000/2003 Terminal Services using the logging tool
To configure the Zetafax printer and Zetafax daemon to log to the ImageMAKER logging tool when documents are printed, step through the following:
- Log onto the terminal server as a user with Administrative rights.
- Browse to the shortcut for the daemon, which will be placed in Documents and Settings\All Users\Start Menu\Programs\Startup.
- Modify the shortcut so it reads: c:\windows\system32\zfdaemon.exe -Q
- Browse to the printers folder, then right click on the Zetafax printer and go to properties.
- Click on the Device Settings tab.
- Click on Debugging options and select enabled.
- Set Debug Options to Log to logging tool.
- Click Apply and then OK to exit of the printer properties dialog box.
- Before signing on to a client session, log into the console and start imglog.exe. Only one instance of imglog should run per machine.
- When a client session logs on, you should see a burst of about 15 lines appear in the ImageMAKER Activity logger window so you know logging is correctly enabled.
DOCTIFF rendering add-on
To enable logging on DOCTIFF add the following line to the Options section of the setup.ini file, which is located in the zfax\SYSTEM\Z-DB folder.
LogLevel: 0
This will log further information to the server.log file. Send some faxes to reproduce the rendering issue and capture the server.log file, which is stored in the Zfax\SERVER\Z-DB folder.
Zetafax SMTP gateway
On the system which has the Zetafax SMTP server installed, work through the following steps:
- Stop the Zetafax SMTP Server service.
- Run the registry editor (Start|Run| and type 'regedit')
- Navigate to the HKEY_LOCAL_MACHINE\SOFTWARE\Equisys\Zetafax SMTP Server key and add a string value called 'Logfile'.
- Enter a the value as C:\smtp.log (Note: Depending on your system you may need to specify an alternative drive letter)
- Restart the Zetafax SMTP server service and send some faxes via the gateway. You will need to send the log files to Zetafax technical support.
Zetafax Client/Server installation
From Zetafax 9 when the server or client setup programs are run, the following log files are created.
ZF Server installs/upgrades
ZetafaxInstall.log
ZFInstall.Log
ZF Client installs/upgrades (including ZF Printer problems)
WKSETUP.Log
ZETAFAX.LOG
ZFClientInstall.log
ZFPRINT.LOG
ZFPRNINS.LOG
ZFPRNUN.LOG
ZFStreamInstall.Log
These will be found in the installing user's TEMP directory (e.g. C:\Documents and Settings\< username> \Local Settings\Temp). NOTE this is a hidden directory by default.
If running pre Version 9 please do the following to create workstation install logs.
- Click Start, select Run then Browse..
- Browse to the Zfax\system\ folder (where Zfax is the location of the Zetafax server files)
- Highlight the WKSETUP.EXE file then click Open to take you back to the Run window.
- You should now have a path to the WKSETUP.EXE program, Add /L on the end of the path e.g. S:\ZFAX\SYSTEM\WKSETUP.EXE /L
- The installation program will now create a ZFPRNUN.LOG file in the user temp area (i.e. C:\Documents and Settings\< Username> \Local Settings\Temp)
- This file should be sent to Zetafax technical support.
The log files for the Zetafax Exchange Connector are called edk*.log and generally can be located in the temp folder for the profile that installed the connector. If necessary search the local machine for edk*.log.
Under HKEY_CURRENT_USER\Software\Equisys\Outlook Extensions create a string value called TLExt (stands for Trace Log Extensions).
The string should have a value of 1
Reproduce the crash in Outlook.
This should then create some log files in a folder which is probably called 'C:\Program Files\Common Files\System\Mapi\1033'
but might also be called
'C: \Program Files\Common Files\System\< something else MAPI like> ' depending on the OS and Office versions.
The log files will be called:
OutExt.log
ExchExt.log
and Zfolctrl.log (this one might not exist).
Please gather the logs that are created.
WARNING: Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Equisys cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.
How to create a MAPI Trace Log
Create a text file with the following information:
[HKEY_LOCAL_MACHINE\SOFTWARE\Equisys\ZETAFAX\MAPIEXP]
'DebugTrace'=dword:00000001
'TraceFile'='c:\\mapiexp.log'
Rename to MAPIEXP.reg and double click to enter into the registry.
Gather the log from the specified location.
WARNING: Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Equisys cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.
Using the Zetafax Checker
The Zetafax Checker program is used to quickly, and easily gather the Zetafax Server standard log and configuration files. These files can be used to investigate general issues and also provided an overview on an installation.
Please do the following on the Zetafax Server machine in order to obtain Checker files:
- Create a new folder on the desktop, name this Zetafax Files
- On Zetafax Server version 9.0 and later: click on Start, select Programs, then expand the Zetafax folder and click on Zetafax Checker
- On Zetafax version 8.0: open Windows Explorer, then browse to 'Zfax\SERVER' where Zfax is the root folder of the Zetafax server installation, locate and click on ZETAFAXINFO.EXE
- In the Zetafax Checker program click on Save
- In the Save As dialog browse to the Zetafax Files folder on the desktop
- In the File Name box type info.txt
- Click on Save
- If other log files have been specifically requested then copy these to the Zetafax Files folder
- Using a compression program such as WinZip or Windows Compression, zip the folder so that it can be email in to Equisys support.
Last updated: 20th January 2006 (MS/EB)
First published: 4th November 2004 (LD/SV)