The xyz accounting system was created to handle the simple task of managing xyz user account information. It is not elegantly designed or implemented. It is not user friendly. With little effort though, it gets the job done.
A payee may be responsible for any number of accounts and services. Each payee's information is kept in a single plain text file with a particular format. Contact information, account information, and debit and credit history are represented in the file. The file's contents may be manipulated by hand or script.
There is no error checking in the system, so it is absolutely necessary that those working with the system know exactly what they're doing. Hopefully this document will help accomplish that.
All of the files that make up the xyz accounting system are in the ~accounts@xyz.net/ directory.
In ~accounts@xyz.net/ is a directory named data
in which each data file
represents a single payee. As accounts are created, a new data file is created
if the payee does not yet have a file. The data file contains contact
information, a list of all the accounts the payee is responsible for, and a
years worth of account credit and debit transactions. When a payee has no more
open accounts, and has a balance of zero, their data file is deleted.
Each data file is named an integer one larger than the last data file created. It is a simple text file, and elements that are processed with scripts are case sensitive. Elements on each line are separated by colons. A data file is made up of the following sections.
The contact section occupies the first line of the file and has the following format.
Name:Phone:Email
No particular format, though it usually is a first and last name. The person we contact regarding the accounts in the file.
Consisting only of numbers (no dashes or spaces), minimally seven digits long, but may be longer. Usually the number where the afore mentioned Name can be reached.
Normal format, username@dom.ain. Where the monthly bills are sent.
The account section begins on the second line of the file, contains any number of account entries, one per line, in alphabetical order, and its end is marked with a blank line. In this way, a single payee, contact, and bill can cover multiple accounts. Each line consists of the following parts.
Username:Type:Area:Status
The account username, all lowercase, no more than eight characters long.
Account type information such as pricing is contained in the script which works on the accounting records. The following are the current account types.
We have to collect sales tax, so I need to know in which area the account is used. The tax rates are in the script that process the records. The following are possible values.
This is used in a few different ways. If they are tax free and if so how. If the account is to be free (not charged for). And sometimes a file will stay open because of a balance still remaining, so I need to know if the accounts with are closed so they don't get charged again. So this field can have one of the following values.
The transaction section begins after the accounts section and a blank line. Each line represents an transaction in the account. The transaction section is trimmed monthly to represent one years worth of historical data, or long enough to include their last payment. Entries have the following format.
Date:Description:Amount
The date is stored as the number of days since 1/1/70 (unix style). For example, the date 7/1/99 would be written as 10773, and 7/8/99 as 10780.
There is no enforced format for this field (other than it not contain a colon),
but it generally has one of three forms. If there is a charge, it looks
something like username, type, area status
, for a credit FIRST NAME
ON CHECK / SECOND NAME ON CHECK
, and a miscellaneous entries, Special
Entry Here
.
Positive amounts represent credits or payments, negative amounts are charges for services. The minimal number of digits are used to represent values ($20.00 is 20, $0.50 is .5, and $0.00 is 0).
Here are some sample data files, each trying to highlight a variety of accounting situations you might need to express.
Steve Shannon:2358921:ze1@xyz.net ze1:normal:homer:tax 10618:zeenax, normal, first month free:19 10623:zeenax, normal, homer tax:-21.1 10651:zeenax, normal, homer tax:-21.1 10658:STEVEN L. SHANNON:27.2 10681:Bounced Check:-27.2 10681:Bank Fee:-1.5 10682:zeenax, normal, homer tax:-21.1 10708:ZE1:30 10712:ze1, normal, homer tax:-21.1 10731:STEVEN L. SHANNON:40 10743:ze1, normal, homer tax:-21.1 10773:ze1, normal, homer tax:-21.1
To provide the customer with their first month of service free, we credit their
account on the day it was created with the right amount to counter next month's
automatic charge for a full month. For this example, their account was created
1/27/99 (10618), so service from 1/27/99 to 2/27/99 should be free. So we made
and entry on the day the account was created, 1/27/99 (10618), crediting their
account $19.00 with the description zeenax, normal, first month free
.
When billed on 2/1/99 (10623), they were left with only $2.10 due, effectively
charging them for service from 2/28/99 to 2/30/99 only, as it should be.
Here we can see the handling of a bounced check. The check in question is dated 3/8/99 (10658) for $27.20. On 3/31/99 (10681), that credit was taken away, and the processing fee from the bank was also passed along with an additional entry.
You will also see that the user changed their username, as they were last
charged for the zeenax
account on 4/1/99 (10682), then later for only
ze1
. They will continued to be charged for ze1
since that is
the name of the account mentioned on the second line of the data file (the only
line of the account section).
Marcus Bradley:2356919:bradleymarcus@webtv.net webtv75:dialup:homer:tax 10749:webtv75, dialup, homer tax:-12.1 10773:webtv75, dialup, homer tax:-15.82 10782:MARCUS BRADLEY:27.92
Here is a WebTV user. Notice the type of account is dialup
, and the
account name used for authentication is not related to their email address since
it is provided by WebTV.
Tim Mullikin:2356213:tmull@xyz.net mary:mailbox:borough:tax tmull:normal:borough:tax 10378:Previous Balance:-19.65 10408:tmull, normal, borough tax:-20.4 10431:MARY DONLON:61.95 10439:tmull, normal, borough tax:-20.4 10470:tmull, normal, borough tax:-20.4 10500:tmull, normal, borough tax:-20.4 10531:tmull, normal, borough tax:-20.4 10532:TIMOTHY MULLIKIN / MARY DONLON:80.8 10561:tmull, normal, borough tax:-20.4 10592:tmull, normal, borough tax:-20.4 10623:tmull, normal, borough tax:-20.4 10651:tmull, normal, borough tax:-20.4 10682:tmull, normal, borough tax:-20.4 10693:mary, mailbox, borough tax:-3.1 10692:TIMOTHY MULLIKIN / MARY DONLON:101.2 10712:mary, mailbox, borough tax:-5.1 10712:tmull, normal, borough tax:-20.4 10743:mary, mailbox, borough tax:-5.1 10743:tmull, normal, borough tax:-20.4 10773:mary, mailbox, borough tax:-5.1 10773:tmull, normal, borough tax:-20.4
There are two accounts here, a normal
account and a mailbox
account, as represented by the second and third lines. You can see that the
mary
mailbox was added 4/12/99 (10693), and was charged for a fraction of
that month 4/12/99 4/30/99.
You can see that they like to pay for month in advance by the large payments made every few months.
We also see that they have been online for over a year, since the first line
in the transaction section dated 6/1/98 (10378) was generated after a script
deleted entries older than a year, and carried their balance over with the
entry, Previous Balance
.
Bill de Creeft:2358924:decreeft@xyz.net decreeft:normal:homer:tax decreeft:space:homer:tax 10541:Previous Balance:0 10561:decreeft, normal, homer tax:-21.1 10561:decreeft, space, homer tax:-5.27 10570:KACHEMAK AIR SERVICE, INC.:26.37 10592:decreeft, normal, homer tax:-21.1 10592:decreeft, space, homer tax:-5.27 10596:KACHEMAK AIR SERVICE, INC.:26.37 10623:decreeft, normal, homer tax:-21.1 10623:decreeft, space, homer tax:-5.27 10637:KACHEMAK AIR SERVICE, INC.:26.37 10651:decreeft, normal, homer tax:-21.1 10651:decreeft, space, homer tax:-5.27 10666:KACHEMAK AIR SERVICE, INC.:26.37 10682:decreeft, normal, homer tax:-21.1 10682:decreeft, space, homer tax:-5.27 10694:KACHEMAK AIR SERVICE, INC.:26.37 10712:decreeft, normal, homer tax:-21.1 10712:decreeft, space, homer tax:-5.27 10716:KACHEMAK AIR SERVICE, INC.:26.37 10743:decreeft, normal, homer tax:-21.1 10743:decreeft, space, homer tax:-5.27 10748:KACHEMAK AIR SERVICE, INC.:26.37 10773:decreeft, normal, homer tax:-21.1 10773:decreeft, space, homer tax:-5.27 10779:KACHEMAK AIR SERVICE, INC.:26.37
This customer has an additional service on the same account. They have the
decreeft
normal account, and on that same account as shown by the second
line in the account section, additional webspace as represented by space
.
They also pay their bill monthly.
Bob Shavelson:2354068:keeper@xyz.net keeper:normal:homer:nonprofit keeper1:mailbox:homer:free keeper2:mailbox:homer:free keeper3:mailbox:homer:nonprofit 10378:Previous Balance:120 10408:keeper, normal, homer nonprofit:-20 10439:keeper, normal, homer nonprofit:-20 10470:keeper, normal, homer nonprofit:-20 10500:keeper, normal, homer nonprofit:-20 10531:keeper, normal, homer nonprofit:-20 10561:keeper, normal, homer nonprofit:-20 10561:keeper2, mailbox, homer free:0 10561:keeper1, mailbox, homer free:0 10561:keeper3, mailbox, homer nonprofit:-5 10560:COOK INLET KEEPER:5 10592:keeper, normal, homer nonprofit:-20 10592:keeper2, mailbox, homer free:0 10592:keeper1, mailbox, homer free:0 10592:keeper3, mailbox, homer nonprofit:-5 10623:keeper, normal, homer nonprofit:-20 10623:keeper2, mailbox, homer free:0 10623:keeper1, mailbox, homer free:0 10623:keeper3, mailbox, homer nonprofit:-5 10633:COOK INLET KEEPER:150 10651:keeper, normal, homer nonprofit:-20 10651:keeper1, mailbox, homer free:0 10651:keeper2, mailbox, homer free:0 10651:keeper3, mailbox, homer nonprofit:-5 10682:keeper, normal, homer nonprofit:-20 10682:keeper1, mailbox, homer free:0 10682:keeper2, mailbox, homer free:0 10682:keeper3, mailbox, homer nonprofit:-5 10712:keeper, normal, homer nonprofit:-20 10712:keeper1, mailbox, homer free:0 10712:keeper2, mailbox, homer free:0 10712:keeper3, mailbox, homer nonprofit:-5 10743:keeper, normal, homer nonprofit:-20 10743:keeper1, mailbox, homer free:0 10743:keeper2, mailbox, homer free:0 10743:keeper3, mailbox, homer nonprofit:-5 10773:keeper, normal, homer nonprofit:-20 10773:keeper1, mailbox, homer free:0 10773:keeper2, mailbox, homer free:0 10773:keeper3, mailbox, homer nonprofit:-5 10778:COOK INLET KEEPER:150
These folks have a normal account, keeper
, and added three mailboxes on
12/1/98 (10561), keeper1
, keeper2
, and keeper3
. They are
charged for keeper
and keeper3 as a nonprofit (no sales tax), but
keeper1
and keeper2 are free, and are charged $0.00.
Although all accounting duties can be accomplished by simply editing the data files in an appropriate manor, the following scripts help to make things a little more efficient.
The scripts are written in Perl (probably not very well as they were the other's first), so if you want to see what they're doing, feel free to take a look at them. They are located in the ~accounts@xyz.net/ directory.
~accounts@xyz.net/balance datafile
This script was made because the data files store dates in an unfamiliar form, and contain only a transaction history, and not a current balance. This script will print a report with the dates in a common form, current balance, and contact name and phone for an account.
If you get a funny result, you may not have given it a data file. It doesn't
have a pager, so if the results you're looking for scroll by, just pipe it into
more
(~accounts@xyz.net/balance datafile | more).
~accounts@xyz.net/enter
Must be run in the ~accounts@xyz.net/data/ directory. It aids in the entering
of payments, modifies data files to reflect those payments,
and creates or appends to two files in the accounts
directory,
tape
and iai
.
It will prompt you for information and if the question has a default value, it will appear in parenthasis. The take the default value, just enter, to give it a new value, enter the value. To quit at any time, hit Ctrl-C. If your paging through some results and want to quit, hit q. The following are details on the script's prompts.
grepprogram to search the data files. Enter anything that might be found in the data file of the account you're looking to credit.
unix style, as described in the Data Files Format Date section. Enter the date on the check, or the current date if you're entering cash.
" / "separating lines. Cash is entered as
Cash.
tapesumscript.
~accounts@xyz.net/next
This script should be run only on the first of each month to bill customers. It charges each account (by making appropriate entries to the data files), trims the data file transaction section to include only the last year's worth of payments, and sends out account statements via email from accounts@xyz.net.
~accounts@xyz.net/tapesum tape*
Takes a tape file and gives a sum of all the payments represented within, as well as the sum of payments made within each of the tax areas. The possible tax areas are as follows.
These are other files generated by the scripts or people used in the accounting system. They are located in the ~accounts@xyz.net/ directory.
Standard .forward file used by the mail system, that when present, will have
email sent to the account (in this case the accounts
account) forwarded
to the email address present in the file.
All bills have a return address of accounts@xyz.net, so the .forward file should contain the email address of the those responsible for such things.
This file is generated by the enter
script,
and document what accounts have been credited by payments that have been entered
into the system. If the file does not exist, it will be created, and if it does
exist, entries will be appended to the end of the file.
When a deposit of entered payments is to be made to the bank, the generated iai
file, iai
, should be renamed. The form should be iaiMMDD.txt
,
where MM
is the month, and DD
is the day the file is being
renamed. In this way, there will be tapeMMDD.txt
files that contain the
accounts credited by payments for each bank deposit.
I'm not sure what this file is used for, it was requested by IAI.
This file is just used to help remember when people want their accounts closed out. It is not used by any scripts. Simply append to the end of the file a line containing the username, some white space, and the date the account should be closed. Delete lines as the accounts are closed.
This file is generated by the enter
script,
and document payments that have been entered into the system. If the file does
not exist, it will be created, and if it does exist, entries will be appended
to the end of the file.
When a deposit of entered payments is to be made to the bank, the generated tape
file, tape
, should be renamed. The form should be tapeMMDD.txt
,
where MM
is the month, and DD
is the day the file is being
renamed. In this way, there will be tapeMMDD.txt
files that contain the
payments for each bank deposit.
The file can be printed to accompany your deposit at the bank. It is also used
by the tapesum
script.