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:

<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>

<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>

<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>

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.