Using the Async Professional Logging Facilities

Sometimes when attempting to debug a communications problem while using Async Professional components, it’s useful to examine what’s happening with the components and the port at the lowest levels. Async Professional provides access to this via a set of properties in TApdComPort (TApdWinsockPort also has them) supporting what we at TurboPower refer to as “Dispatcher Logging”.  TurboPower support technicians often need to request a Dispatcher Log from a customer as part of general procedures for diagnosing particular problems.

The main property involved is Logging, which, at the basic level, just turns the feature on and off.  Setting the Logging property to tlOn at design time will cause the ComPort component to generate a log for the session which includes entries indicating what was sent out the port, what came in, the activities of internal “triggers”, and possibly reports from other Async Professional components that may be in the project.  When the application terminates, the current state of the log is written to a “log file”.

The log itself resides in a “circular buffer” in memory, so it never gets beyond a certain size; the oldest entries are deleted to make room for new entries.  The maximum size of this memory buffer is determined by the LogSize property.  This defaults to 10kB, but can be set to 64kB in Delphi 1, or up to 2GB in any of the 32-bit compilers.

The name used for the log file defaults to APRO.LOG, and, by default, is saved in the root of the C: drive; but this can be changed via the LogName property.   This field may include a full path name as well as an alternate file name.  An exception will be raised if the path doesn’t exist; but note that Async Professional will gladly clobber any file that may already exist, so be careful what you provide for the filename.

In the absence of any alternative handling of the Logging property, by default any current file named as what’s in the LogName property will be overwritten with the current state of the logging buffer when the application exits. 

At design time, the only choice is whether the log starts off turned on or off (despite the list of options shown in the Logging property’s property editor).  At run time, however, there are several additional options for the Logging property, that give you more options for working with the log file:

These work rather like commands to the log.  In the case of tlAppend and tlDump, after setting Logging to one of these, Logging is turned off, just as if you’d set Logging to tlOff yourself; so if you want logging to continue you must follow such a change by explicitly setting Logging to tlOn once again.

Most Async Professional components send notifications of critical internal events to the log, so you can watch what (for instance) a DataPacket or Protocol component is doing as well as just what’s happening to the ComPort. 

The internal layout of a Dispatcher Log file looks something like so:

The first column is a timestamp, representing the time elapsed from the time Dispatch Logging was turned on, measured in milliseconds.

The second column is the major category of entry Log entry, the third column breaks up the categories a bit further, the forth column provides additional information related to the event (often a handle or data count), and the remaining column adds any additional information that could be useful for the event being logged; this is where the raw data sent or received over the port is logged.

Please see the DISPLOG.TXT file that ships with Async Professional for more information on the interpretation of the log file.

This site is not affiliated, endorsed, or otherwise associated with the entity formerly known as TurboPower Software. The owners and maintainers of Aprozilla.com were merely meager employees of the aforementioned organization, providing this site out of the pure goodness of their collective hearts.

Last updated: July 22, 2003.