BANAL version 0.03

Chapter 2: Basic Client Usage

The use of the bk client is very simple. We assume that the server is running and that you are familiar with the concepts presented in 1.2.

A list of commands and help is available by typing:
bk help.

You can obtain specific help on a command by typing:
bk help <command>.

It is important to note that the -L option is used with the directory that contains the BK subdirectory (in this distribution it is found in the lib directory). You should only need to use this option if you move the lib directory relative to the bin directory.

The -p must be passed the server name and port number in the form SERVER:PORT. This command line option will override both the default server and port and any values set by the environment variable BKPORT. BKPORT, if set, must also be of the form SERVER:PORT.

The client's default setting for the server name is localhost. You may change this in the bk script if it is easier than setting an environment variable or creating an alias.

2.1: Add/Edit/Delete Commands

These commands are used for manipulating records in a table. To see a listing of tables refer to section 3.3.

Here is a sample usage for modifying data in the invoice table. This usage would be identical (except for the command name) for any other existing table. The modify command is always the same as the table name.

invoice -- Create, delete, or edit an invoice

bk invoice [ -t template ] [ ID ]
bk invoice -o [ -t template ] [ ID ]
bk invoice -d ID
bk invoice -i

'Invoice' creates and edits invoice values using an ASCII form. An invoice is an entry in the bookkeeping system.

With no arguments, 'invoice' creates a blank invoice form and invokes the user's editor. When the form is saved, an invoice of the form invNNNNNN is created. If an ID is given on the command line either that named ID will be created or, if the ID already exists, the invoice can be modified. Use the -t option to indicate an existing entry that will supply initial values.

The -d flag deletes the named invoice. The -o flag causes 'invoice' to write the invoice form to the standard output, instead of invoking the editor. The -i flag causes 'invoice' to read an invoice form from the standard input.

2.2: List Commands

These commands are used for listing records (or the field information) from the table. You may limit the records that are listed by using an expression. See the expression section (6.1) for more details. To see a listing of tables refer to section 3.3.

Here is a sample usage for listing data in the invoice table. This usage would be identical (except for the command name) for any other existing table. The listing command is always the plural form of the table's name.

invoices -- Display a list of invoices

bk invoices [ -f SEP ] [ -r ] [ -c FIELDS ] [ expression ]
bk invoices [ -f SEP ] [ -F ] [ -T ] [ -D ]

Reports a list of all invoices currently known to the system. An expression may be any valid RDB expression. The -f option specifies the field seperator (eg. -f : or -f XXX). The default seperator is a tab space (<TAB>).

Use the -r flag to generate an entire RDB file instead of just a listing of entries.

The -c flag lets the user specify which fields (and which order) to report the entries. FIELDS must be one single argument if more than one field is requested (ie. -c 'Field1 Field2')

This command may also return the field names (-F), the field types (-T), and the Field descriptions (-D).

2.3: Generating Invoices

This command is used to generate an invoice based on information in the charge and invoice tables. Here is the usage:

print -- Generate a PostScript invoice

bk print InvoiceID

Print generates a PostScript file containing information from the InvoiceID and related Charges.

If the invoice has no Date set then it defaults to today and this value is saved in the database.

2.4: Generating Financial Statements

Use this command to generate financial statements.

Currently there is only the income statement available.

2.5: Running Memorized and Recurring Transactions

For more information on recurring/memorized transaction refer to chapter 4. A special note should be added that you do not need to run this command if you only have recurring transactions (as opposed to memorized). The server will run the recurring transactions for you.

Here is the general usage of the runbatch command:

runbatch -- Process recurring transactions

bk runbatch [ -d date ] [ -m mID ] [ cmds ... ]

Runbatch may be used to force the processing of recurring transaction or to run a memorized transaction. Optional commands may be added on the command line and they will evaluated before each transaction's commands.

Use the -m option to specify the Recurrence ID of a memorized transaction (ie. NextDate is empty and Interval is 'never'). Use the -d option to specify the date to run under. This may be useful, for example, to get ahead in your work.

It should be noted that the server will process recurring transactions automatically and periodically.