Appendix D - Export Account Information File Format #

Introduction #

This appendix describes a family of file formats which are exported by the Max2 system to provide details of accounts and transactions on those accounts in a given month. The operations which generate these files are described in External Account Processing.

The file formats in the family are used for different purposes. The first was created for use by the Bristol and Gloucester Gliding Club (BGGC, Nympsfield) to allow member's account details to be displayed on a separate member accessible computer. Later versions of the format have been created for use by Booker Gliding Club (BGC).

Each of the files is a simple text file in the Windows "ANSI" (Windows-1252) character set. It consists of a sequence of lines, each terminated by carriage return/line feed (CRLF) combinations.

The Java code which deals with some of the formats exported for BGC use allows blank lines (lines consisting of only space and horizontal tab characters) and lines beginning with '#' or';' as comments. It also allows the last line to not be terminated by CRLF. It is recommended that these generalisations be supported by any other readers produced in future.

Each record line in the file starts with a letter which indicates what type of record it is. The remainder of the line contains the data of the record. There is no space or other character between the record type letter and the record contents.

All of the formats in the family use the same letter to record type mapping and the same ordering of records within the file. The only difference between the formats is whether they allow or require each of the record types to be present. In other words, each format is a subset of an abstract "master format" - the subsets being created by making certain record types either optional or prohibited.


Generic File Syntax #

The following extended BNF syntax defines the "master format" describing all files in the family.

Generic Record Order Syntax
File    ::=    FileHeader
Account*
FileHeader    ::=    F: File Header
V: File Version
M: File Month
J: Subject?
X: Text*
S: Club Address*
L: Mail Server?
G: Mail User Name?
H: Mail Password?
K: Intermessage Delay?
Y: Reply Address?
O: From Address?
U: Undisclosed Recipient Address?
I: Attachment*
Account    ::=    AccountHeader
Transaction*
AccountTail?
AccountHeader    ::=    A: Account Number
N: Name
E: EMail Address?
P: Mobile Phone Number?
R: Brought Forward Balance?
Transaction    ::=    T: Transaction Text
D: Debit
B: Balance Following Transaction
AccountTail    ::=    C: Carried Forward Balance
W: Aerotow Credit

Though different record types may or may not be present in individual file formats or individual files within each format, when they are present they will be in exactly the order specified in this syntax. For example, if a 'J' record and one or more 'X' records are present in a file then the 'X' records will follow the 'J' record with no intervening records.


Specific File Syntaxes #

Each of the syntactic items in the above generic BNF can be required, optional or prohibited in each of the specific file formats in the family. We use the following characters to indicate the number of instances of each item which can be present in each format:

Record Presence Key
1    Exactly one instance - the item must be present but must not be duplicated.
x    Prohibited - the record must not be present.
?    Optional - may or may not be present but no more than one may be present.
*    Zero or more - any number may be present, including none.
+    One or more - any number may be present, excluding none.

In each case, this notation indicates the number of instances of the item which may be present within the enclosing item. For example, where the A: Account Number record is shown as occurring once this means once within the AccountHeader which occurrs once within the Account. The Account can occur many times within the file so the A: Account Number record must occur the same number of times. This notation does not imply that the A: Account Number record must appear exactly once in the whole file. Sometimes it's worth stating the bleedin' obvious, just to be sure.

Record Presence
Item BGGC
Export
EMail
Statement
Bulk
EMail
SMS
Text
 
FileHeader 1 1 1 1
 
F: File Header 1 1 1 1
V: File Version 1 1 1 1
M: File Month 1 1 1 1
J: Subject x 1 1 x
X: Text x * * +
S: Club Address x * x x
L: Mail Server x 1 1 x
G: Mail User Name x ? ? x
H: Mail Password x ? ? x
K: Intermessage Delay x ? ? x
Y: Reply Address x ? ? x
O: From Address x 1 1 x
U: Undisclosed Recipient Address x x 1 x
I: Attachment x * * x
 
Account * * + +
 
AccountHeader 1 1 1 1
 
A: Account Number 1 1 1 1
N: Name 1 1 1 1
E: EMail Address x 1 1 x
P: Mobile Phone Number x x x 1
R: Brought Forward Balance 1 1 x x
 
Transaction * * x x
 
T: Transaction Text 1 1 x x
D: Debit 1 1 x x
B: Balance Following Transaction 1 1 x x
 
AccountTail 1 1 x x
 
C: Carried Forward Balance 1 1 x x
W: Aerotow Credit 1 1 x x

Record Details #

F: File Header #

The File Header record contains the general format of the file within the family. Its contents can be:

F: File Header Record Contents
Max2 Statement Export A BGGC (Nympsfield) style statement export.
Max2 Statement EMail Statement data to be e-mailed to individual account holders.
Max2 Bulk EMail Specification of a single message to be e-mailed to each of one or more account holders.
Max2 SMS Text Specification of a single message to be sent to the mobile phones of each of one or more account holders.

V: File Version #

Contains the number "1". If the file format is changed in the future this number will be changed.

Readers should reject files with version number higher than they understand.

M: File Month #

Contains the month of the transactions or account information validity in the file in the format yyyy-mm where yyyy is the year and mm is the month (with a leading zero for months before October).

J: Subject #

Contains the subject to be included on a bulk e-mail message. Typically something like "[Booker] Newsletter - 2003 March".

For statement e-mail messages, the prefix placed before the title of the statement. Typically, "[Booker]".

May be an empty string even in files in which this record is required.

X: Text #

Where this record is allowed there may be more than one instance. Each 'X' record contains one line of text.

For e-mailed statements it is included at the bottom of the statement, centred and emphasized to play the same role as messages commonly included in that position on printed statements.

For bulk e-mail statements, the contents of the X records, if present, are included as the text body of the message. If no X records are present then the first attachment is examined. If it is suitable to be the body of the message (i.e., if it is text/plain or text/html) then it is used, otherwise a blank message body is added.

For SMS text messages, the contents of the X records are the contents of the message to be sent.

An SMS sender should treat text in multiple X records as separated by a space if there is no equivalent of a line break which can be sent. Max2 does not limit the length of this text (e.g., to 160 characters) - an SMS sender should report an error if the text is too long.

In each case any leading or trailing white space on each line is ignored. Also leading and trailing lines which contain only whitespace are ignored. Whitespace X records which are preceded and followed by non-whitespace X records are included in the message.

S: Club Address #

These records are included in statement e-mail messages. They are inserted on the statement in the place normally used for the sender's address in letters (upper right).

White space at the beginning and end of lines and white space records at the beginning or end of the S record sequence are treated as for X: Text records.

L: Mail Server #

For files which indicate the sending of e-mail messages this record contains the address of the SMTP server through which the messages are to be sent, for example, "smtp.nildram.co.uk".

This record cannot be empty.

G: Mail User Name #

For files which indicate the sending of e-mail messages this record contains the user name to be used to authenticate (logon) to the SMTP server (ESMPT AUTH).

The record should be omitted if unauthenticated SMTP is to be used.

H: Mail Password #

Obfuscated version of the password to be used with the user name in the G record. Typically should be present if and only if the G record is also present.

The obfuscation applied to the password is a transformation of all printable ASCII characters (excluding space) to, normally different, printable ASCII characters. Other Windows-1252 characters are not transformed. The purpose of this obfuscation is to avoid making the password too obvious to casual users who don't need access to it but who happen to look at the contents of this control file or other text files which might contain the password (Max2's .INI files). It's not intended to be secure against somebody who sets out to find the password with any amount of determination.

K: Intermessage Delay #

Delay (integer number of seconds) to be inserted between email messages sent to abide by ISP spam throttling rules, etc. If omitted then no delay is inserted.

Y: Reply Address #

This optional record indicates the e-mail address to which replies to e-mail messages should be sent. Typically "office@bookergc.nildram.co.uk".

If this record is omitted or empty then no reply-to address is included in the message.

O: From Address #

The e-mail address which is to be shown as the source of the e-mail message. Typically "max2@bookergc.nildram.co.uk".

This record cannot be empty.

U: Undisclosed Recipient Address #

For bulk e-mail messages, in which each of the recipients is included as a BCC: (to avoid showing everybody everybody else's e-mail address, for those who are sensitive about such things) the content of this record is included as the TO: address. Every RFC-822 message is supposed to have a TO: address, although this rule is often ignored.

Typically, something like "Numerous Undisclosed Recipients <nur@bookergc.nildram.co.uk>".

This record cannot be empty.

I: Attachment #

File names of files which are to be included as attachments to statement and bulk e-mail messages.

The first attachment will be used as the message body if it is of MIME type text/plain or text/html and there are no X: Text: Text records in the file.

None of these records can be empty.

A: Account Number #

This record marks the start of the information for a particular account and contains the Max2 Account Number. This is from one to four letters or digits starting with a letter.

This record cannot be empty.

N: Name #

Contains the name of the account holder in the format Surname, Nickname.

This record may be empty, though that's a bit unlikely.

E: EMail Address #

Contains the e-mail address of the account holder to be sent a statement or included in the distribution list of a bulk e-mail message.

This record cannot be empty.

P: Mobile Phone Number #

Contains the mobile 'phone number of the account holder.

This record cannot be empty.

R: Brought Forward Balance #

Contains the money balance of the account at the start of the month. The balance is in the format of a pound sign, possibly a negative sign, one or more digits of pounds, a decimal point and two digits of pence. A negative amount indicates an account in debt.

T: Transaction Text #

Contains a textual description of the transaction, starting with the date in dd/mm/yy format (leading zeroes included where required). Any start-of-month transactions will have the day part as "--" (two minus signs).

D: Debit #

Contains the amount the account is debited by the transaction in the format of a pound sign, possibly a negative sign, one or more digits of pounds, a decimal point and two digits of pence. A negative sign indicates a credit to the account.

B: Balance Following Transaction #

Contains the money balance of the account after the transaction has been applied. The balance is in the format of a pound sign, possibly a negative sign, one or more digits of pounds, a decimal point and two digits of pence. A negative amount indicates an account in debt.

C: Carried Forward Balance #

Contains the money balance of the account after all the transactions in the month have been applied. The balance is in the format of a pound sign, possibly a negative sign, one or more digits of pounds, a decimal point and two digits of pence. A negative amount indicates an account in debt.

The value on the C balance record will normally match that of the R record if there are no transactions on the account or the last B record if there are transactions. It is provided to make processing slightly simpler for reading programs (not having to distinguish these two cases) and in case any transactions which do not appear on the statement affect the balance (there shouldn't be any).

W: Aerotow Credit #

Contains the amount the account is in credit for aerotow after application of all of the transactions so far entered for the month. It is in the form of one or more digits and is in feet. It should normally be a multiple of 100ft.