\documentstyle[]{article} \title{CBBSH {\protect \\} CheckBook
Balancer -- Shell Version {\protect \\} Alpha Release}

\def\cbbsh{{\tt cbbsh}}
\def\kwiken{{\sf Kwiken}}
\author{Christopher B. Browne}
\begin{document} 
\maketitle 

Copyright \copyright{} 1994 Christopher B. Browne -- \hbox{\tt
  cbbrown@io.org}.

\begin{verbatim}
$Id: cbbtxt.tex,v 1.2 1994/10/28 04:07:57 cbbrowne Exp cbbrowne $
\end{verbatim}

CBBSH is partly based on another work in progress, {\tt cbb}, a
checkbook balancer written in perl and tcl by Curtis Olson --
\hbox{\tt curt@sledge.mn.org}.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

\section{Introduction}
\subsection{What is \cbbsh{}?}

\cbbsh{} is intended to represent a ``replacement'' for much of the
functionality of the former Intuit (now part of the Micro\$oft empire)
Corporation's infamous personal finance product known as something
like \kwiken{}.\footnote{It is possible that I am misspelling the name
  of Bill's new purchase.} {\sf Real Soon Now,} once it reaches a bit
more robust stage, it will allow me to de-install my copy of {\tt
  DOSEMU}, regain a few MB of disk space, and be rid of MS-DOG
entirely.

\cbbsh{} can generally do the following:
\begin{itemize}
\item Maintain financial transactions in a variety of accounts
\item Import and export {\tt .QIF} files that are compatible with most
  personal finance systems (see~\ref{importqif})
\end{itemize}

At this point it's a {\em little\/} weak on reporting tools, but since
the source code is readily available, it shouldn't be difficult to
``hack up'' something in Perl that will be readable.  My own
proclivities would tend towards creating \TeX{}-formatted material
when printouts are necessary; this would provide reports that are {\em
  significantly\/} more attractive than those produced using the
commercial packages.

\subsection{What about all these different versions?!?}

There are at least two distinct {\tt cbb} programs; the ``other'' one
is written using {\tt tclx}, provides a spiffy X-Windows interface,
and is generally quite a lot more similar to the commercial software
than \cbbsh{}.

\cbbsh{} is written ``in UNIX style,'' with a variety of comparatively
small programs that are run directly from the shell.

The primary advantages to using {\tt cbb} are that it's friendlier,
and has a user interface similar to that used in the commercial
personal finance packages.

The primary advantages to \cbbsh{} are that:
\begin{itemize}
\item It doesn't require X-Windows,
\item It's small,
\item It's more usable on an ad-hoc basis, as it doesn't need much
  ``loading time.''  This is at least partly a result of it being
  small.
\item It only uses one language ({\tt perl}), instead of two ({\tt
    perl} and {\tt tcl}), which simplifies the learning curve for
  those wanting to learn how to customize it.
\item It can be readily embedded in other applications (see the
  crontab example in section~\ref{crontab}).

  This is something that GUI-based systems are not well-suited to handle.

\end{itemize}

That being said, any rivalry between the two versions will hopefully
be friendly. The intent is for \cbbsh{} to be at the very least file
compatible with {\tt cbb}. Better still would be for there to be
significant amounts of shared code. I'd like to be able to run {\tt
  cbb} when running X-Windows, use \cbbsh{} when I'm not (which is the
case most of the time), and have them use exactly the same data.

\section{Installation} \label{installation}

You need to know the following things to set \cbbsh{} up:
\begin{enumerate}
\item Where you're going to put the {\tt perl} shell scripts.\\ In my
  case, it's all in {\tt /home/cbbrowne/business/quicken/bin}.  You
  might want to put them into {\tt /usr/local/bin},
  
  Move the executable files there.
  
\item Where you can put the {\tt cbbshutils.pl} ``engine.''
  (see~\ref{cbbutils.pl})
  
  In my case, it went into {\tt /usr/lib/perl}, which is the typical
  location of perl {\tt require} files. Since I'm doing almost
  continuous development, this is actually a symbolic link to the
  working copy in {\tt /home/cbbrowne/business/quicken/bin}.
  
  Pick a spot, make sure it's in your {\tt PATH}, and copy the files
  there.  A {\tt chmod} and/or {\tt chown} may be necessary.
  
\item Where you're going to put the data.
  
  In my case, this is {\tt /home/cbbrowne/business/quicken/dat.} You
  need to ensure that this directory exists, and then edit {\tt
    cbbshutils.pl}, and change the line near the top that looks like:
\begin{verbatim}
$home="/home/cbbrowne/business/quicken/dat/";
\end{verbatim}
  
  Put the name of your favorite directory there. Ensure that there's a
  {\tt "/"} at the end, otherwise your ``cash'' file might get named
  {\tt /home/john/finances/datcash.txn.dir}, instead of the hoped-for
  {\tt /home/john/finances/dat/cash.txn.dir}. This will probably work
  out ok, but be fairly confusing.
  
\item Set up the ``bank accounts.''  These will include bank accounts
  proper, credit cards, as well as the ubiquitous ``cash.''
  
  If you are currently using another product and intend on exporting
  data to {\tt cbb}, you may need to change your set of account names
  {\em slightly}.
  
  You need to have two pieces of data for each account: a {\bf name}
  and a {\bf description.}
  
  The {\bf name} can be of any size, but needs to be something that
  represents a valid piece of a filename, as it's what you'll be using
  to reference the account.  Put a bit of thought into the name, as
  you're likely to use it a lot.
  
  It cannot contain spaces or colons ({\tt ":"}).  Spaces will result
  in ambiguity when trying to reference the account from the command
  line, and are otherwise evil.  Colons are used internally as field
  separators; while they {\em may\/} work now, they probably won't in
  the long term.\footnote{The separator should probably be changed to
    some uncommon string, say {\tt \&=\%}, instead.  This would
    increase the database size somewhat, but would allow people to
    make use of all but the oddest sorts of account codes.  Perhaps in
    a later version, in cooperation with the {\tt cbb} efforts.}
  
  Case is {\em not significant,} as the name will be transformed to
  lower case.
  
  \begin{description}
  \item Valid names: {\tt cash}, {\tt chequing}\footnote{Here in
      Canada, as a less-rebellious vestige of the British Empire than
      the USA, we use the word ``cheque'' instead of the US ``check.''
      Chancellor of the Exchequer and so forth\ldots}, {\tt
      MasterCard}, {\tt annoyingly$\_$long$\_$name}.
    
  \item Invalid names: {\tt cash 1}, {\tt master card}, {\tt Invest:IRA}
  \end{description}
  
  You can then pick something more descriptive for the {\bf
    description}.  The description isn't currently used for anything,
  but could certainly be referenced when producing reports.
  
  My set of accounts looks something like:\\
  \begin{tabular}{||l|l||}\hline
    Name & Description \\ \hline
    cash & Cash \\
    chequing & Canada Trust Chequing \\
    savings & Bank of Montreal Savings \\
    amex & American Express \\
    lvisa & Laurentian Bank VISA \\
    mc & Canada Trust Mastercard \\
    \hline
  \end{tabular}
  
  and would be created as follows using {\tt makeacct}
  (see~\ref{makeacct}):
\begin{verbatim}
dantzig:>% makeacct cash 'Cash'
dantzig:>% makeacct chequing 'Canada Trust Chequing'
dantzig:>% makeacct savings 'Bank of Montreal Savings'
dantzig:>% makeacct amex 'American Express'
dantzig:>% makeacct lvisa 'Laurentian Bank VISA'
dantzig:>% makeacct mc 'Canada Trust Mastercard'
\end{verbatim}
  
\item Import {\tt .QIF} files (see~\ref{importqif}) \\ If you're
  running \kwiken{}, then you will want to get some {\tt .QIF} files
  so that your old data is available to \cbbsh{}.
  
  \begin{enumerate}
  \item Make the \kwiken{} account names consistent with the names you
    picked in the previous step.  ({\em e.g.} -- chequing, savings,
    amex, lvisa, etc.) This is necessary so that inter-account
    transfers will be correctly referenced.
    
  \item For each account for which you wish to move information over,
    create a {\tt .QIF} file.  The start date should be the earliest
    possible date; {\tt 01/01/01} probably will work, and be the best
    choice.  Similarly, the end date should be the latest possible
    date; {\tt 01/01/99} is probably fine, unless you've been into
    predicting your financial transactions of 1999.
    
  \item Import the {\tt .QIF} file, using {\tt importqif}
    (see~\ref{importqif}):
\begin{verbatim}
dantzig:>% importqif chequing /msdos/quicken/ctchq.qif
\end{verbatim}
    
    Check the balances for the account (using {\tt listos})
    (see~\ref{listos} to ensure that the data came over correctly.
    
  \end{enumerate}
  
\end{enumerate}

\section{Summary of {\tt cbbsh} commands}

The various commands in {\tt cbbsh} are here documented by functional
area:
\begin{itemize}
\item Transaction Creation -- creating transactions to record your
  financial activities.
\item Reconciliation -- agreeing the transactions to those that are
  recorded by your financial institution
\item Reporting -- listing the transactions on the system
\item {\tt .QIF} file handling -- importing and exporting data for use
  with other personal finance software
\item System Setup -- creating/modifying accounts and categories
\item Other -- For those special commands that just don't fit anywhere
  else.  These tend to be commands that do ``internal'' stuff like
  transaction logging and translation.  If you need to use them, you
  really need to use them.  If not, then don't worry about them.
\end{itemize}

\subsection{Transaction Creation}

\subsubsection{\tt txn} \label{txn}

This is perhaps the most important single script in \cbbsh{}; this is
the script that is used to actually generate transactions.  It does
quite a bit of error checking, a database lookup to determine the
category name, and if you have a category name short enough to be
ambiguous, it will provide a list of matching categories and allow you
to pick one.  Note that the {\tt -t} option stands for ``today,'' and
is translated to today's date

Here's several examples:
\begin{itemize}
\item Here's a transaction for which there is no faintly matching category.
{ \small
\begin{verbatim}
dantzig:> txn trash -t '123' 'A&W' 'Root Beer' 45.00 'This shouldn't work'
No matches found for root beer!
\end{verbatim} }
\item The same transaction with the ``R'' category matches with several
  categories.  You can then pick which category starting with ``R'' is the 
  right one. 
{ \small
\begin{verbatim}
dantzig:> txn trash -t '123' 'A&W' 'R' 45.00 'This is ambiguous'
Transaction dated [941029]  Ref # [123] to [A&W]
Amount: DR        45.00 CR         0.00 Re: This is ambiguous

Category code [r] is ambiguous:
 #  Category Name      Long Description
----------------------------------------------------------
 0 Rent                 Rent::
 1 Recreation           Recreation:Recreation Expense:
 2 Rent Income          Rent Income:Rent Income:T
 3 RRSP                 RRSP:Reg Retirement Sav Plan:
 4 Rent Paid            Rent Paid:Rent Paid:T
 5 Returns              Returns:Returns & Allowances:T
 6 Repairs              Repairs:Repairs:T
Pick one: (invalid entry to abort): 1
   0 94/10/29    123 A&W                                     45.00 DR
      Recreation     This is ambiguous                        0.00 CR
_____________________________________________________________________
Latest Balance for trash is      0.00
\end{verbatim} }

\item Backdated transaction
{ \small
\begin{verbatim}
dantzig:> txn trash 930101 '' 'Mom' 'Gift' 50.00 'I am crass'
Transaction dated [930101]  Ref # [] to [Mom]
Amount: DR        50.00 CR         0.00 Re: I am crass

Category code [gift] is ambiguous:
 #  Category Name      Long Description
----------------------------------------------------------
 0 Gifts                Gifts:Gift Expenses:
 1 Gift Received        Gift Received:Gift Received:T
Pick one: (invalid entry to abort): 0
\end{verbatim} }

\item Backdated gift; the amount is therefore entered as a negative number.
{ \small
\begin{verbatim}
dantzig:> txn trash 931225 '' 'Aunt Judy' 'Gift' -50.00 'Nice Aunt'
Transaction dated [931225]  Ref # [] to [Aunt Judy]
Amount: DR         0.00 CR        50.00 Re: Nice Aunt

Category code [gift] is ambiguous:
 #  Category Name      Long Description
----------------------------------------------------------
 0 Gifts                Gifts:Gift Expenses:
 1 Gift Received        Gift Received:Gift Received:T
Pick one: (invalid entry to abort): 1
   0 93/12/25        Aunt Judy                                    0.00 DR
   Gift Received     Nice Aunt                                   50.00 CR
_______________________________________________________________________
Latest Balance for trash is      0.00
\end{verbatim} }

\end{itemize}
\subsubsection{\tt tf} \label{tf}

{\tt tf} is short for ``transfer,'' and is used to simplify/shorten
the process of creating the transactions required when transferring
money from one account to another.  The formatting of arguments is
very similar to those in {\tt txn}.

At this point, it's possible that it's a little over-verbose.

Example:
\begin{verbatim}
dantzig:~/business/quicken/bin> tf -t 'n/a' trash t2 50000 'Big transfer'
txn 'trash' -t 'n/a' 'Funds Transfer' '[t2]' 50000 'Big transfer'
txn 't2' '-t' 'n/a' 'Funds Transfer' '[trash]' -50000 'Big transfer'
Ok - found [t2]
   0 94/10/29    n/a Funds Transfer                   50000.00 DR
            [t2]     Big transfer                         0.00 CR
_______________________________________________________________
Latest Balance for trash is      0.00
Ok - found [trash]
   0 94/10/29    n/a Funds Transfer                       0.00 DR
         [trash]     Big transfer                     50000.00 CR
_______________________________________________________________
Latest Balance for t2 is      0.00
\end{verbatim}

\subsubsection{\tt cash} \label{cash}

This exists to simplify the processing of those ever-common cash
transactions that don't have ``reference numbers'' (unless you are one
of those unusual individuals who records the serial numbers of the
currency you receive and use).

\begin{verbatim}
dantzig:> cash
Incorrect arguments
cash [date] [payee] [category] [amount] [optional comment]
example: cash -t KFC Lunch 3.86

dantzig:~> cash -t 'Jimmy the Greek' 'Lunch' 4.27
Ok - found lunch
   0 94/10/29    n/a Jimmy the Greek              X       4.27 DR
           Lunch                                          0.00 CR
_______________________________________________________________
Latest Balance for cash is     55.14
\end{verbatim}

\subsubsection{\tt deltxn} \label{deltxn}

This is used to delete transactions from the system.  At this time,
this is the only form of ``editing'' that is available; to delete the
old, and add a replacement.  {\em Real Soon Now, there may be some
  sort of form screen coming.}

Moreover, the only transactions that can be deleted are those which
have not yet been marked {\tt "X"} as reconciled.  Once they're
reconciled, they're not available to be deleted.  Which has a certain
amount of logic:
\begin{quote}
  If the transaction was reconciled, you must have verified it against
  the bank statement;\\ The {\em amount\/} certainly must be
  correct;\\ If the transaction is deleted, then that will throw off
  some previous reconciliation.
\end{quote}

In addition, I got the ordering and the interface ``for free'' by
using the outstanding transaction data created by {\tt buildos} and
used by {\tt listos} (see~\ref{listos}) and {\tt tag} (see~\ref{tag}).
In effect, {\tt deltxn} is a variant of {\tt tag} which, instead of
tagging a transaction as one that's been verified against bank
information, indicates that it should be discarded.

Example:
\begin{verbatim}
dantzig:~> listos trash
Listing Outstanding Transactions for Account [trash]
   0 94/10/29    123 A&W                                 45.00 DR
      Recreation     This ought not to work               0.00 CR
_______________________________________________________________
   1 93/1/1          Mom                                 50.00 DR
   Gift Received     I am crass                           0.00 CR
_______________________________________________________________
   2 93/1/1          Mom                                  0.00 DR
   Gift Received     I am crass                          50.00 CR
_______________________________________________________________
   3 93/12/25        Aunt Judy                            0.00 DR
   Gift Received     Nice Aunt                           50.00 CR
_______________________________________________________________
   4 94/10/29    n/a Funds Transfer                   50000.00 DR
            [t2]     Big transfer                         0.00 CR
_______________________________________________________________
                 Previously Reconciled Balance:    0       0.00
       Items marked for current reconciliation:    0       0.00
                          Items not yet marked:    5  -49995.00
dantzig:~> deltxn trash 1
Deleted item 1
   1 93/1/1          Mom                           D     50.00 DR
   Gift Received     I am crass                           0.00 CR
_______________________________________________________________
                 Previously Reconciled Balance:    0       0.00
       Items marked for current reconciliation:    0       0.00
                          Items not yet marked:    4  -49945.00

\end{verbatim}

The next time the account is reconciled (using {\tt clearos}), the
transaction will be deleted.

\subsection{Reconciliation Commands}

\subsubsection{\tt clearos  } \label{clearos}

This is used when you think an account reconciliation is complete; you
enter the verified balance (usually from a bank statement or credit
card statement).  If this amount agrees with the net ``book balance''
(which is equal to the sum of the previously reconciled ({\tt X})
transactions and the ones currently tagged as having gone through
({\tt *}), then the tagged transactions are marked with {\tt X} and
you can consider the reconciliation for the current month complete.

See also subsection~\ref{tag} -- {\tt tag}.

\subsubsection{\tt listos   } \label{listos}

This is used to list all of the transactions that have not been marked
{\tt "X"} as reconciled.

They are placed in order based first on the {\tt \$check} field, then
sorted by date, and lastly by the transaction key (to break all ties;
we can't afford any ambiguity here).

They are numbered starting at $0$, and that number is what you use to
refer to transactions when tagging or deleting them
(see~\ref{deltxn},~\ref{tag}).

Sample:  Here's a sample of an outstanding transaction report for the
{\tt [gold]} Mastercard account.
{\small
\begin{verbatim}
dantzig:>% listos gold
Listing Outstanding Transactions for Account [gold]
   0 94/8/4          SmithBooks                                  13.91 DR
           Books                                                  0.00 CR
_______________________________________________________________________
   1 94/9/24         Computronix                                 95.28 DR
       Comp-Soft     Sundry CDs                                   0.00 CR
_______________________________________________________________________
   2 94/10/4         Consumers Distributing                      66.31 DR
           Music     Walkman & Batteries                          0.00 CR
_______________________________________________________________________
   3 94/10/8         Salem Storehouse                            63.50 DR
           Music                                                  0.00 CR
_______________________________________________________________________
   4 94/10/17        Canada Trust                                 0.00 DR
      [Chequing]                                                687.96 CR
_______________________________________________________________________
                         Previously Reconciled Balance:   38    -687.96
               Items marked for current reconciliation:    0       0.00
                                  Items not yet marked:    5     448.96

\end{verbatim}
} % small

\subsubsection{\tt tag      } \label{tag}

This is used to mark those transactions that have been verified as
having passed through the account, generally by checking them off
against the bank statement.

{\tt tag} must be used in conjunction with {\tt listos}, which lists
the outstanding transactions, along with their tag numbers.

Sample:  Tagging transaction 2 (see section~\ref{listos}):
{\small
\begin{verbatim}
dantzig>% tag gold 2
Tagged item 2
   2 94/10/4         Consumers Distributing               *      66.31 DR
           Music     Walkman & Batteries                          0.00 CR
_______________________________________________________________________
                         Previously Reconciled Balance:   38    -687.96
               Items marked for current reconciliation:    1      66.31
                                  Items not yet marked:    4     382.65
\end{verbatim}
} %\small

The {\tt -u} option can be used to untag a transaction (removing the
{\tt *}). 
Sample:  Untagging transaction 2 and 3 (where 3 isn't tagged)
{\small
\begin{verbatim}
dantzig>% tag gold -u 2 3
Cleared item 2
   2 94/10/4         Consumers Distributing                      66.31 DR
           Music     Walkman & Batteries                          0.00 CR
_______________________________________________________________________
Item 3 is not tagged
   3 94/10/8         Salem Storehouse                            63.50 DR
           Music                                                  0.00 CR
_______________________________________________________________________
                         Previously Reconciled Balance:   38    -687.96
               Items marked for current reconciliation:    0       0.00
                                  Items not yet marked:    5     448.96

\end{verbatim}

\subsection{Reporting Commands}

\subsubsection{\tt gt -- {\sf grep transaction}} \label{gt}

This is used to search for transactions with whatever characteristics
are desired.

There is an attempt to allow user-specified sorting criteria, but it
doesn't seem to work properly yet.

\subsection{{\tt .QIF} File Processing}

\subsubsection{\tt importqif} \label{importqif}

This is used to load in a set of transactions from a {\tt .QIF} file.

This program is a little smarter than that; if a particular import
file contains a list of categories, {\tt importqif} will put the
associated category names and descriptions into the category DBM file.
{\tt .QIF} files may also contain a list of accounts; they will be
ignored, as \cbbsh{} handles the accounts fairly differently.

\subsection{Setting Up the System}

\subsubsection{\tt makeacct } \label{makeacct}

Its usage for creating accounts described in
Section~\ref{installation}, {\tt makeacct} is used to create new
accounts or to change their names.

The account name cannot contain spaces or colons ({\tt ":"}); it
really should not contain any sort of punctuation, and should be a
reasonably ``pithy'' and short account description, as you'll be using
it every time that you do anything with that account.

Example:
\begin{verbatim}
dantzig>% makeacct gold 'Canada Trust Gold Mastercard'
\end{verbatim}

\subsubsection{\tt createcat} \label{createcat}

If there is a need to create new income or expense categories, or to
modify the descriptions of those that already exist, this is the
program to use.

{\bf Database Lecture Mode on:}
\begin{quote}
{\em Unlike\/} \kwiken{}, one cannot readily rename a category {\em
key,\/} as the category name is in fact used as the ``primary key'' for
storage of category information.  The category table here could be
visualized as:
\begin{tabular}{||l||l|l||} \hline
Primary Key & Description & Tax Code \\
(Category) & (Category Desc.) & \\ \hline
Salary & Salary & x \\
Int. Inc. & Interest Income & x \\
CPP & Canada Pension Plan Deductions & x \\
Food & Groceries &  \\
\vdots & \vdots & \vdots \\ \hline
\end{tabular}

Any place that references ``Interest Income'' uses {\tt Int. Inc.} as
the key by which to look things up, so that if we wish to change {\tt
  Int. Inc.} to something else (like {\tt IntInc}), each and every
reference needs to be changed.  Since that's a nasty sort of thing to
have to do, it's typically a ``forbidden operation.'' (I've told
clients that I couldn't make a software change that they wanted for
this very reason.  They wanted to be able to edit an identifier field
that intrinsicly ought not to be edited.)  If you don't know {\em
  exactly\/} what you're doing, a primary key change can mess up a
database very badly.

For this reason, on many systems (and I strongly suspect that \kwiken{}
is one such), the primary key is hidden from the user, and the apparent
key is a ``short form'' of the longer description.  The table might look
like:
\begin{tabular}{||l||l|l|l||} \hline
Primary Key & Short Description & Description & Tax Code \\
(Hidden) & (Short Category) & (Category Desc.) & \\ \hline
XA2F & Salary & Salary & x \\
S2F8 & Int. Inc. & Interest Income & x \\
SAF2 & CPP & Canada Pension Plan Deductions & x \\
9SDA & Food & Groceries &  \\
\vdots & \vdots & \vdots & \vdots \\ \hline
\end{tabular}

In this table, one can change the short description (which {\em
  appears\/} to be the primary key) safely and easily.  A transaction
would internally refer to {\tt XA2F} instead of {\tt Salary}, which
creates some translation problems that I suppose that we'd rather
avoid here.  The application would do translation behind the scenes
every time that you look at a category so that you never need to see
the ``primary key.''

I expect that most people have tuned out by this point.
\end{quote}
{\bf Database Lecture Mode off}

In short, this means that you can't readily change the transaction
descriptors, and if you do, you need to make sure that you:
\begin{itemize}
\item Change them {\em everywhere,}
\item Really know what you're doing, and
\item Change them {\em everywhere.}
\end{itemize}
This is all highly undesirable.

At this point, {\em no\/} use is made of the description field.  It's
available for people generating reports, and is primarily there in
order to support the {\tt .QIF} file format for both import and export
purposes.

{\tt createcat} now has the {\tt -d} option that allows you to delete
categories.

\subsection{Other Commands}

The following commands are not readily categorized; they generally
perform functions that might be categorized as ``system
administration'' such as backup and restoration of data.

\subsubsection{\tt buildos }  \label{buildos}

This program goes through and builds up an up-to-date list (and
counts/totals) of all of the transactions for a given account
categorized by whether or not they have been ``cleared.''

There are three statii: 
\begin{enumerate}
\item Uncleared -- either blank or {\tt "N"}
\item Tagged to clear -- {\tt "*"}
\item Previously cleared -- {\tt "X"}
\end{enumerate}

Transactions with status {\tt "X"} are not included in the list, as
they have been handled in previous account reconciliations.

Unless problems are encountered, {\tt buildos} does not normally print
anything out.

Example:\\
\begin{verbatim}
dantzig:>% buildos chequing
\end{verbatim}

The outstanding list is usually created when needed, so that you will
not commonly need to run it yourself.

\subsubsection{\tt showtxn} 

This is a transaction report that list the {\tt txn} command required
to create the transaction(s).  This would be useful for creating
``memorized scripts'' that could be modified as necessary and played
back later.

Example:
\begin{verbatim}
dantzig:>% showtxn chequing -c rent
txn chequing 940101 110 'My Landlord' 'Rent' 600.00 'issued Dec.31/93'
txn chequing 940201 111 'My Landlord' 'Rent' 600.00 'issued Dec.31/93'
txn chequing 940301 112 'My Landlord' 'Rent' 600.00 'issued Dec.31/93'
txn chequing 940401 113 'My Landlord' 'Rent' 600.00 'issued Dec.31/93'
txn chequing 940501 114 'My Landlord' 'Rent' 600.00 'issued Dec.31/93'
txn chequing 940601 115 'My Landlord' 'Rent' 600.00 'issued Dec.31/93'
dantzig:>% showtxn chequing -c rent > rent.sh
dantzig:>% vi rent.sh
dantzig:>% chmod u+x rent.sh
dantzig:>% ./rent.sh
\end{verbatim}

This could be used in conjunction with {\tt cron} or a diary system like
{\tt remind} to automatically generate transactions.

\subsubsection{\tt rawdump}

{\tt rawdump} dumps all of the transactions in a dbm file in a
very-lightly-formatted form.  This is the same format as is used for
the transaction log file (on my system, this file is called {\tt
  \small /home/cbbrowne/business/quicken/data/alltxns.log}).

This provides you with a dump of the entire transaction file
(including keys) which is fairly readable, and which could be
processed by some other program. Sorting it and then using {\sf RCS}
to maintain a long-term record of changes might be a candidate.

Its close partner is {\tt rawread}, which will happily fill a {\tt
  cbb} database with transactions in this format.

\subsubsection{\tt rawread}

{\tt rawread} will read in transaction log information and put it into
the database.  This would be useful for rebuilding the {\sf dbm} files
if (horror of horrors) they get messed up, or for other sorts of
system transfer or recovery.

This is the ``scalpel'' command that will be able to modify anything
anywhere at any time.

It probably should not be used by anyone without ``surgeon-level''
experience with the data structures, as it will be able to do {\em
  evil things.}

The only ``public'' use for this would probably be in doing recovery
using the log files.

\subsubsection{\tt cbbutils.pl} \label{cbbutils.pl}

This file contains virtually any subroutine that is used in more than
one of the other {\tt perl} scripts; it results in a minimizing of
duplicated code, and provides services to all of the utilities.  It
shouldn't be made {\em too\/} large or featureful, as it's loaded by
{\em all\/} of the \cbbsh{} scripts, but certainly should be the
repository of any centralized services.

It might make sense, if this grows, to split it into pieces and only
{\tt require} the necessary portions of it for any given {\tt perl}
script.

Some suggestions on the use of things in the utilities file:
\begin{itemize}
\item In general, {\em do not\/} use the data structures directly, if at
all possible.  Use the functions in {\tt cbbshutils.pl.}

The functions have been built up to do most of the data management
automatically, so that all of the things that need to be done together
are done together.  This helps with maintaining system integrity.

So, for instance, use {\tt \&put\_TXNS()} to insert transactions.  It
will, in addition to updating the transaction information,

\begin{enumerate}
\item Log the transaction, which is a reasonable method of handling crash
  recovery, and
\item Update the related balances.
\end{enumerate}

This has the beneficial side-effects that if additional functions are
needed (for instance, updating a ``expense total''), that can be added
in a single place.  

Moreover, if the underlying database system changes (perhaps to one of 
the RDBMS's like Postgres or Ingres), there's only one place where 
that requires changing code, instead of 50 unpredictable spots.

The things that {\em should\/} be used include:
\begin{itemize}
\item {\tt need\_txn(\$file)}, to open a particular account,
\item {\tt need\_os(\$file)}, to ensure that the outstanding list
  exists for a particular account,
\item {\tt blank\_os(\$file)}, to re-initialize a particular account's
  outstanding item list,
\item {\tt blank\_bal(\$file)}, to re-initialize a particular account's
  balance table,
\item {\tt pad()}, which isn't the {\em nicest\/} named routine, but
  is useful for forcing numbers to be 2 digit zero-filled,
\item {\tt create\_trans()}, which puts a new transaction into the
  system.  It is an important function in that it requests new
  transaction keys.
\item {\tt add\_os()}, which 
\end{itemize}

Routines that {\em should not\/} be used outside {\tt cbbshutil.pl} include:
\begin{itemize}
\item {\tt adj\_bals()}
\item {\tt get\_next\_key()}
\end{itemize}
These are used internally, and are the pieces most likely to need to
change.

\item So what else is important?

\end{itemize}

\section{Sample Customizations}

\cbbsh{} does not include any particular provision for the
memorization of transactions (ala \kwiken{}'s {\bf M}emorize - C-m).
It does, however, provide a unique opportunity for the user to create
their own customized transaction schemes.

\subsection{ATM Withdrawal}

For instance, here is {\tt perl} code to implement an ATM cash
withdrawal. I call it {\tt atm}.

\begin{verbatim}
#!/usr/bin/perl
# atm - create an ATM transfer from [chequing] to [cash].
if ($#ARGV != 1) {
    print "Incorrect arguments\n";
    print "atm [date] [amount]\n";
    print "Transfers [amount] from chequing to cash\n";
    print "example: atm -t 80\n";
    die -1;
}
($date, $amount) = @ARGV;
$tf = sprintf "tf $date n/a chequing cash %9.2f ''", $amount;
system($tf);
\end{verbatim}

and I would use this by typing:
\begin{verbatim}
dantzig:>% atm -t 60      # considerably shorter than the alternative: \
           tf -t n/a chequing cash 60 ''
\end{verbatim}

\subsection{Mel's Diner}

Supposing I regularly have lunch at a particular ``greasy spoon,'' I
can save a lot of typing by creating the following:

\begin{verbatim}
#!/usr/bin/perl
# diner - Ate at Mel's Diner, and typically have the scary $2.99 special
if ($#ARGV > 2) {
    print "Incorrect arguments\n";
    print "diner [optional date] [optional amount] [optional comment]\n";
    print "bought lunch at Mel's Diner; the `special' is \$2.99\n"
    print "example: \ndiner # I ate at the diner today\n";
    print "diner 940403\n";
    print "diner 940509 4.55 'Had the Pepto-Bismol promotion.'\n"
    die -1;
}
($date, $amount, $comment) = @ARGV;
if ($date eq "") {
   $date = "-t";
}
if ($amount eq "") {
   $amount = 2.99;
}
$txn = sprintf "txn $date n/a 'Mels Diner' Lunch %9.2f '$comment'", $amount;
system($txn);
\end{verbatim}

\subsection{{\tt crontab} Integration} \label{crontab}
This starts to get fairly perverse; one could always put those
``periodic entries'' into the {\tt crontab} file. You wouldn't need
to bother entering the bi-weekly pay stub that's the same all the
time; {\tt cron} could enter it every other Friday for you.

\appendix

\section{Areas requiring changes}

The following are a fairly random set of proposals for functional
and/or architectural changes, that may at some point get looked at
further.

\begin{itemize}

\item There's a need for some sort of ``transaction editor.''  Right
  now, there's solely the choices of {\em adding\/} or {\em deleting\/}
  transactions.

  One of the ``form'' packages may be good for producing a full screen
  transaction editor.  If it can be compressed to a couple of lines,
  then this could extend to multiple transactions on the screen.

\item Change the field separator from the current {\tt ":"} (which
  precludes using that useful character within a field) to something
  less likely to be useful to the user.

  Preferably using punctuation; the use of punctuation that \TeX{}
  tends to ``barf at'' is a bonus.  How about {\tt "\&=\%"}, or a
  single doublequote {\tt "}?  These are values that one does {\em
    not} want to have within fields\ldots

  Needs agreement.

\item Create a {\tt Configure} script.

\item Reporting is quite weak right now. In  particular,  there  are  no
summary reports, or anything resembling an income statement. (A FASB  or
CICA Statement of Changes in Financial Position is a whole other  matter
altogether.)

\item Dates should absolutely, positively, contain the century number,
  at least internally.

{\bf Systems Development Lecture Mode on:}
\begin{quote}

  Anyone who creates software at this late date in the millenium that
  doesn't do so should be {\em taken out and shot.} I say this
  professionally. Two additional characters per date is a relatively
  cheap thing in terms of disk space and memory, and simplifies life
  immensely.

  {\em ``But this software won't be in use that long.''} 

 I said {\em ``taken out and shot,''} and mean it. Most of the
 computer software I've done maintenance on over the past year is
 stuff that is being hit or will soon be hit badly by the ``2000''
 problem, and most of it was ``temporary solutions'' of the late '80s
 where the people that paid for it said {\em ``This software couldn't
 possibly be in use that long.''} Such people tend to {\em lie,} and more
 importantly this is no excuse for poor system architecture.

 Let's get it right the first time, and avoid the problems altogether.
 Using 4 digit year dates will help encourage other people to do the
 same, and discourage them from using 2 digits, which is a {\bf good
 thing.}
\end{quote}
{\bf Systems Development Lecture Mode off}

 Needs agreement.

\item RDBMS\\ In the longer term, it would be nice to use an actual
  relational database management system, as opposed to the
  not-quite-so-robust-or-functional DBM files.

  Particular advantages to the use of an RDBMS are that you may get
  automatic sorting, faster selection of ranges, some data integrity 
  checking, transaction logging, and the likes.  Balances probably come
  ``for free'' here.  The building up of lists of transactions ({\em
  e.g.} in {\tt buildos} and in {\tt showtxn}) becomes far faster since
  the system can skip over unneeded transactions altogether.

  Hard; put this off 'til well after the ``beta'' stage.

  Code-wise it would be {\em fairly\/} involved.  Nonetheless, there is
  an attempt in the code to minimize the amount of direct use of {\sf
  DBM} files so that if and when this change comes in, the ill effects 
  are minimized.
  
  A more major concern is the fact that all of the Linux RDBMS  packages
  appear to be fairly complex to set up. Most require  TCP/IP  services,
  a DBMS administrator account, and all sorts of  little  complications.
  And some people may be interested in running \cbbsh{} or {\tt cbb}  on
  systems on which they do not have root privileges,  or  on  (horrors!)
  non-Linux systems.
    
  The {\sf Typhoon} libraries may be an alternative; I need to see how
  queries would be constructed there.

\item Backup transaction files\\ People should certainly think about
  doing this periodically; the Transaction Logging capability that's
  included hopefully simplifies the task.

  It's not obvious that this needs to be sophisticated; a shell script
  that {\tt tar}s and {\tt gzip}s the {\sf dbm} files is probably all
  that's needed.

\item Transaction Logging\\ I like the idea of logging every
  transaction created into a semi-hidden file off somewhere, with
  date-stamping and the likes.  If this can be done in a manner in
  which the data can readily be re-used in case of DBM ``data loss,''
  it would be ideal.  It might be neat to use RCS to help with this.

  Easy to provide {\em some\/} support; RCS support may be more
  ``interesting.''

\item Investment Tracking\\ \kwiken{} has a fair bit of functionality in
  the area of tracking purchases of stocks, bonds, mutual funds.  It's
  not {\em great,\/} mind you, but it definitely does exist.  \cbbsh{}
  currently {\em does not handle this at all.}

  Handling this would probably involve more work than is involved in
  the rest of the {\tt cbb} system.  I don't want to even think about
  it right now.

\item BUG: Transaction Deletion\\
  An anomaly can occur here.  In particular, one can delete one
  side of a transfer transaction, orphaning the other.  This will be
  particularly annoying if the transaction that's left has already
  been reconciled; this all throws things somewhat out of balance.

  The problem is mostly troublesome for the {\tt cash} account where
  one is likely not to be reconciling it.  If one end of a credit card
  payment gets missed, that {\em will\/} get caught at the time of the
  next reconciliation.

\item Export of {\tt .QIF} files \\ A prototype of this exists in the
  {\tt cbb} family; need to port it to \cbbsh{}.

\item Moving towards Perl 5 \\ The most readily available ports of Perl
  5 for Linux do not have {\sf DBM} support compiled into them.  As a
  result of that, and the fact that version 5 isn't quite universally
  available, it's not yet time to move to it.

  However, the code should ideally not make use of features that are
  unique to version 4.036 to minimize the cost of the changeover when
  version 5 becomes ubiquitous.
  
\end{itemize}

\section{Known Bugs}
\begin{itemize}
\item The ``updated'' balance printed out by {\tt txn} isn't correct.
\item {\tt buildos} isn't always run when needed.
\end{itemize}

\section{Squashed Bugs}
\begin{itemize}
\item
\end{itemize}

\end{document}
