PhoneLog - a standard for phone log-files based on SGML


Copyright © 1998-2006 Dipl.-Inform. Kai Hofmann. All rights reserved!

The PhoneLog Standard

Description

It seems that there was no standard for log files used to log modem connections etc. As you can see programs like PhoneBill (by Raymond Penners) support very different log file formats. I decided that it was time to create a standard based on SGML defined in ISO8879 and on ISO8601 which defines date/time representations.

SGML uses the ISO8859-1 characterset as base, so it can be used on every platform. On the other hand SGML gives the log file a real structure defined by the DTD.

The advantage of using SGML is that these log files have a structure, can be interchanged at ease with other SGML applications like databases, wordprocessors or calculation software.

By supporting this standard with your software you give the user the possibility to create or evaluate log files with software from different platforms. You also get a standard which is easily extended should a need occur.

Books which were consulted in creating this software:

The SGML Handbook
Charles F. Goldfarb
First Edition
Oxford University Press, Walton Street, Oxford (USA) 1990
ISBN 0-19-853737-9

Implementation

The format of PhoneLog log files is defined by the DTD. For those of you who are not familiar with SGML I will try to explain the basics:

In the DTD the elements for a document type will be defined. Normally all elements have a start-tag and an end-tag.

<!ELEMENT PHONELOG - O (((OUTGOING|ENTRY) | INCOMING | MARK)*)>

descibes the element <PHONELOG> consisting of zero or more elements of the type <OUTGOING>...</OUTGOING>, <INCOMING>...</INCOMING> or <MARK>...</MARK>.

<ENTRY>...</ENTRY> is there for backward compatibility to version 1.x and has the same meaning as <OUTGOING>...</OUTGOING>

Each element can consist of other subelements or it is a final element containing character data (CDATA). If an element has subelements, these will be defined as follows:

() : Expressions within a group are treated as a unit for other operations.
,  : All of the connected elements must occur in the same sequence as defined.
|  : One and only one of the connected elements must occur.
*  : Unit can occur 0 or more times.
?  : Unit can occur 0 or 1 time.

Optional some elements may have their own attributes:

<!ATTLIST PHONELOG	version		NUMBER	1
                        revision	NUMBER	2>

<PHONELOG> means that the defined default version/revision will be used.
<PHONELOG version="2" revision="0"> defines version/revision 2.0.

Examples

A log-file entry can be freely formatted:

But this formating is preferred:

<OUTGOING>
  <HOST>
    <NUMBER>2187550</NUMBER>
  </HOST>
  <START>
    <DATE>1995-02-15</DATE>
    <TIME>16:30:00</TIME>
  </START>
  <END>
    <TIME>17:45:10</TIME>
  </END>
</OUTGOING>

Document type definition version 2.0

<!DOCTYPE PHONELOG [

<!ELEMENT PHONELOG		- O (((OUTGOING|ENTRY) | INCOMING | MARK)*)>
<!ELEMENT (OUTGOING|ENTRY)	- O (PROGRAM?,HOST+,((START,KNOCK*,END?,PERIOD?) | BUSY | NOANSWER))>
<!ELEMENT INCOMING		- O (PROGRAM?,HOST*,((START,KNOCK*,END?,PERIOD?) | RING))>

<!ELEMENT HOST			- - (NUMBER,HOSTNAME?,REASON?)>
<!ELEMENT (NUMBER|HOSTNAME|
           REASON|DATE|TIME|
           PERIOD|PROGRAM|
           MARKNAME)		- - CDATA>
<!ELEMENT (BUSY|NOANSWER|
           RING|START)		- - (DATE,TIME)>
<!ELEMENT KNOCK			- - (HOST?,DATE?,TIME)>
<!ELEMENT END			- - (DATE?,TIME)>
<!ELEMENT MARK			- - (PROGRAM,MARKNAME)>

<!ATTLIST PHONELOG			version		NUMBER				2
                                        revision	NUMBER				0>
<!ATTLIST (OUTGOING|ENTRY|INCOMING)	type		(unknown|voice|fax|modem)	unknown
                                        bps		NUMBER				0>
<!ATTLIST PROGRAM			version		NUMBER				1
                                        revision	NUMBER				0>
<!ATTLIST MARK				number		NUMBER				0>
<!ATTLIST BUSY				knocked		NUMBER				0>
]>

Semantic of DTD elements

PHONELOG

Root element that identifies the logfile format. It has the following attributes:

version: Version number of the PhoneLog file standard
revision: Revision number of the PhoneLog file standard

OUTGOING | ENTRY (obsolete!)

This entry marks a call as outgoing - i.e. when you make a call to someone. It has the following attributes:

type: Type of the connection - can be one of: unknown,voice,fax,modem
bps: Transfer speed in bits per second of a modem or fax connection

INCOMING

This entry marks a call as incoming - i.e. when someone makes a call to you. It has the following attributes:

type: Type of the connection - can be one of: unknown,voice,fax,modem
bps: Transfer speed in bits per second of a modem or fax connection

MARK

Mark that was written by a logfile analyser software. It has the following attributes:

number: Number of the mark

PROGRAM

Name of the logfile anaylser program which has written the mark. It has the following attributes:

version: Version of the logfile analyser program which has written the mark
revision: Revision of the logfile analyser program which has written the mark

HOST

Description of the host to which you are connected

START

Start date/time of the connection

KNOCK

This element is used when someone knocks you while you are connected to someone other (knocking is an ISDN feature)

END

End date/time of the connection

PERIOD

Duration of the connection (see below for the format)

BUSY

You tried to call a host, but the line was busy. It has the following attributes:

knocked: Number of times you knocked a busy line (knocking is an ISDN feature)

NOANSWER

You tried to call a host, but nobody answers the call

RING

Someone tried to call you, but you can not or would not take the call

NUMBER

Phone number of the host to which you are connected

HOSTNAME

Name of the host to which you are connected - this can be the name of a person or a computer hostname

REASON

Reason for the connection

DATE

Start/End date of the connection (see below for the format)

TIME

Start/End time of the connection (see below for the format)

MARKNAME

Name of the mark - might be helpful for identification

Format for date/time/period

The format for date/time/period is taken from ISO8601 and has the following form:

Time  : hh:mm:ss
Date  : yyyy-mm-dd
Period: hhHmmMssS

To me it looks like ISO8601 missed an important point:

When switching from summer- to winter- time, one hour occurs twice! To distinguish these two hours an 'a' or a 'b' should be added to the time information.

Dipl.-Inform. Kai Hofmann, <webmaster@hofmann-int.de> - Bremen, 2006-12-28