








Novell Accounting Print Server

Version 2.50





Written By Hamish Marson
At the University of Waikato
Hamilton
New Zealand


Internet Address : h.marson@waikato.ac.nz



Program and Documentation are (C) Copyright 1991.









Netware and Novell are registered trademarks of Novell Inc.

DISCLAIMER! The author and the University of Waikato bear no responsibility for any action or disaster as a result of using this program.


Table of Contents


{TOC \o|Table of Contents	i
Licence & Copyright Info	1
Program Description	2
Physical Set-up	2
Running the Program	2
Initialisation	3
File Format	3
Comments	3
Server Name	3
Accounting	3
Output	3
Input	4
File Server Set-up	6
Btrieve Accounting	6
Database Creation	7
Updating Balances	7
CHGBAL	7
Database Access	8
Printer Types	8
Postscript	8
Paintjet	9
Laserjet Series II	9
Laserjet Series III	9
Generic	9
Charon Compatibility	10
Serial Communications	10
Parallel Communications	10
The Screen	11
Accounting Method	11
Updating Balances	11
Step By Step Installation	11
New Program Features (by version)	12
Version 1.0	12
Version 2.00a (not released)	12
Version 2.10b	12
Bugs Fixed (By Version)	12
Version 2.00a	12
Known Bugs (By Version)	13
Version 1.0	13
Version 2.00a	13
Version 2.10b	13
Future Enhancements	13
Btrieve Database Details	i
History Transaction Codes	ii
}
Licence & Copyright Info
This program is released as shareware, and may be used for a free trial period of up to 30 days. After that free trial period, it must be registered with the University of Waikato, or deleted.

The program may be distributed by ftp, BBS, disk and email, as long as it is intact, in archive format (any archive/compression program will do) and all files are present as indicated in the manifest. This program may not charged for by other organisations, except for a reasonable copying fee. The copying fee should be no more than that which would cost the user to download from the nearest source.

The licence to use this program is granted to any registered user. To become a registered user, simply send $75.00 in New Zealand Currency (Bank draft payable on Bank of New Zealand preferred) and the name/address of the organisation using the program. This will entitle the holder of the license to run a single copy of the print server software.

Site licenses may be purchased for the price of $150.00 (NZ), this will entitle you to run as many copies of the server as you wish at a single site.

Registered users will receive support by internet email, or letter if no email is available. Phone messages MAY be answered, however if I am in when you phone support will be offered.

All financial enquiries, payments, registrations etc should be sent c/-

	Computer Services Department
	Private Bag
	University of Waikato
	Hamilton
	New Zealand

Please support this program and its development by registering the software.


Program Description
The Accounting Print Server (from here on referred to as pserv), is an accounting engine written to total up the number of pages used by a print job on a Novell network, that is in the Hewlett Packard Laserjet-PCL language, or Postscript Page Description Language

It runs on a single microcomputer workstation and requires at least 256k bytes of RAM, however it may be advantageous to have more, as this figure has not been fully tested. A single floppy drive for booting and storage of the program and initialisation files, and a network interface card (Ethernet, Token Ring or other Novell Supported Hardware). The program can be booted from a boot ROM, as it reads all initialisation files before logging onto the file servers to be serviced.

The version of netware developed and tested on was Advanced Netware 2.15C, running on 386SX and 386DX machines. The actual server software (pserv.exe) will run on any PC XT/AT machine that is 100% DOS compatible, and maybe many that aren't.. Netware Version 2.1 or later is required, because of the Netware calls that are made to support the functions of the print server.

The server will process the jobs from specified servers and queues and output the resulting file along with a 1 page trailer containing the user name, server and queue of origin, number of pages counted, cost per page, and most importantly the cost of the printout. The final balance of the account and the credit limit are also shown on this page.

Physical Set-up
The physical set-up of the pserv program is as indicated in this diagram. The printers are connected directly to the dedicated machine running the pserv software, which is in turn connected to the novell network medium.


figure {seq figure|1} The physical set-up of the print server and its attached printers.

Running the Program
The operation of the software is very simple. Simply boot the machine that the software is to run on, loading the network interface software, and then run pserv.exe. The following 4 line autoexec.bat file will suffice for an ethernet machine running the original novell ipx drivers.


ipx.com
net3.com
brequest		# only if using btrieve accounting feature
pserv.exe
<EOF>
figure {seq figure|2}, Sample autoexec file for automatically starting the print server
Initialisation
The program expects an initialisation file by the name of server.ini to be in the same directory as that which you invoked the program from. The file may be edited by any ASCII editor, and is in human readable form.

File Format
The file format can be described as follows (a single command must be on a single line by itself, with the exception of a comment):-

Comments

# := comment. Any text after a # is ignored

Server Name

The print server must be named by the line

server [pserv_name]

This line is mandatory, and must represent the name defined in the file servers bindery for the print server object. There is only 1 name per server, and it must be unique among the servers (including all advertising servers)

Accounting

The type of accounting is initialised with the line

accounting [novell | btrieve <btrieve server> <directory path>]

No parameters are needed for the novell accounting, but the btrieve accounting needs the file server providing the btrieve services, and the directory path where the databases have been created. The print server must have access to the directory path where the btrieve database exists, and it must be on the btrieve server.

Output

Outputs are defined with the define statement

define output <output name>
<output defines>
end output

where <output name> must be unique within the server, and can be any name up to 20 characters. The output defines come next, 1 per line, and lastly the line end output to indicate that the output definition is finished.

The output defines consist of the following

printer [postscript | laserjetii | paintjet[xl] | generic]
port [com1 | com2 | com3 | com4 | lpt1 | lpt2 | lpt3 | lpt4]1
params <baud rate  data-bits parity stop-bits>

Legal printer types are
	Type	Description
	postscript	Adobe Postscript Printers (eg LaserWriter, SilentWriter)
	paintjet
	paintjetxl	Hewlett Packard Paintjet printer series
	deskjet	Hewlett Packard Deskjets
	laserjetii	Hewlett Packard Laserjet Series II (HP-PCL Level IV)
	laserjetiii	Hewlett Packard Laserjet Series III (HP-PCL Level V)2
	hpgl	Hewlett Packard Graphics Language.3
	generic	Generic printer, no accounting.

The parameters only apply to the serial ports, and are considered illegal for the parallel port. All I/O addresses for the parallel ports are picked up from the BIOS tables in low memory. The I/O ports for the serial chips are hard coded as the default values specified in the IBM Technical Reference manuals.

The range of bit rates supported for the serial ports is 300, 1200, 2400, 4800, 9600, 19200 and 38400 bps. The databits, parity and stop bits are formatted as 3 characters with no spaces between them. eg 

params 19200 8N1

would be read as 19200 bps, with 8 data bits, no parity and 1 stop bit.

The print server will also attempt bit rates of 57600 and 115200 bps, however as printers that actually operate an interface at this speed are rather hard to come by, these speeds have not been adequately tested.

Input

Inputs are defined with a similar statement

define input
<input defines>
end input

The input defines consist of the following

destination <output destination>
server <file server name>
queue <queue name>
cost <cost per page>
banner [Y | YES | N | NO]

The banner and cost lines are optional and will default to no cost and a printed banner if they are left out of the set-up for that queue.

For any illegal queue description the program will print a short message on the status line of the relevant queue server display. Messages are simple and easy to under stand. There is a full list of errors and their causes at the end of this document.

# PSERV Ver 2.00 set-up config file.
#
server pserv1
#
# Use btrieve accounting with databases in
# res:accounts\printing\*.dat on the server infosys
#
accounting btrieve infosys RES:ACCOUNTS\PRINTING
# Define an output named nec290, with a postscript printer attached
# to com1 at 9600bps,8 bits, No parity, 1 stop bit
#
define  output nec290
printer postscript
port    com1
params  9600 8N1
end output
#
# Define an output named dot1, with a generic printer on lpt1
#
define  output dot1
printer generic
port    lpt1
end output
#
# Define an input from the server FS1, queue NECSILENT and output to
# nec290 with a banner and charge 15 cents per page
#
define input
dest   nec290
server fs1
queue  necsilent
banner yes
cost   15
end input
#
# Define an input from the server FS2, queue NECSILENT and output
# also to nec290, with a banner and no charge per page
define input
dest   nec290
server fs2
queue  necsilent
banner yes
cost   0
end input
#
# Define an input from the server FS1, queue TTYA and output to
# DOT1, with no banner (there will be no charging)
define input
dest   dot1
server fs1
queue  ttya
banner no
end input
#

Figure {seq figure|2} is an example initialisation file with 2 inputs from different servers, going to 1 postscript output, and a pass-through queue, going to a generic (ie no accounting) printer.
File Server Set-up
The file servers to be served must have the print server entered in their bindery (by use of the pconsole utility), with the appropriate privileges to be able to attach to the queues and to charge the users for the pages printed. If btrieve accounting is enabled instead of the default novell accounting calls, the print server must have access to the required directories where the btrieve databases reside. This is done by adding the print server object as a trustee of the database directory with Read,Open,Write rights, or adding the server as a member of a group that has those trustee rights. The print server can have the trustee rights added directly with the utility provided named trustee, or added as the member of a group with the utilities that came with charon 3.1

To add a print server to the file server, the program pconsole is used. To start, type pconsole at the DOS prompt. Select "Print Server Information", (You must have supervisor equivalency to do this), and hit the <INSERT> key. Type in the name of the print server (It must be unique), and hit <RETURN>. A password is not used as of this version, so do not define one for the print server.

Use the <ESC> key to get back to the first menu. Select "Print Queue Information". Now we must have a print queue to spool the print jobs to. Either select an already existing one, or create a new one by pressing <INSERT> and entering a unique name. Now Select the Queue chosen. Next select the "Queue Servers" option. Press <INSERT> and select our new print server. If any other non-accounting print servers are also serving this queue it is advisable to remove them from this  option, using the <DELETE> key. This will happen if you choose an already existing queue. Adjust the Queue Users and the Queue Operators to the required members.

Use the <ESC> key to exit back to DOS.

Now run syscon by typing syscon at the DOS prompt

Select the "Accounting" function, and then "Accounting Servers". Press the INSERT key to bring up a requester for selecting the server type. Select the "Print Server" option. Lastly select the new print server that you have just added.

Lastly use the <ESC> key to escape back to DOS.

Now everything is ready to start the print server.

Btrieve Accounting
New to version 2.00a of the print server is the option of accounting by btrieve database, instead of the default novell accounting calls. This is enabled by the inclusion of a line in the server.ini file, that simply states4

accounting btrieve <bt_server> <volume:path>

where <bt_server> = the local btrieve server where the pserv account has access5.
and <volume:path> is the volume and path of where the btrieve databases reside.

The main feature of this accounting method is that all users will have just one balance for all of the servers that they print from. This alleviates the problem of when one person was using more than one server, if they wished to have only one balance then they would have to run a capture to just one queue on one server no matter where they logged into (ie they always had to attach to the central queueing server). The balances may also be updated by people without supervisor equivalency.

Because of the way that the print server looks up the users for a single account, all users must therefore have the same username on all systems that the print server is serving.

Database Creation
The database files may be created with the batch file create.bat, that accompanies the print server program. Three database files (user.dat, server.dat & account.dat) will be created, from the database description files user.dsc, server.dsc and account.dsc.

The three file will initially be very small (in region of 1-2k each), however they will grow rapidly as new users are added to it. The users are added automatically whenever they are no recognised by the print server. 

Updating Balances
Balances may be updated by anyone with sufficient trustee access to the database directory, instead of having to have supervisor equivalency. There is a small (and simple) program provided to do the updating of the balances (named chgbal.exe), or you can write your own to conform with the standards required by your work-place. Full details of the database are included at the end of this document.

CHGBAL
Balances may be changed with the program included in this distribution. The executable is named chgbal.exe, and it may be used to alter balances by way of Credits and Debits, and also to obtain a printout of the current state of a users account.

The program is very easy to use and requires just 1 parameter on the command line, and a second optional parameter to indicate where the printouts will be directed. If the second parameter is not included or is invalid, printouts will default to your standard printer (ie LPT1:)

The command line syntax is

chgbal <bt_server/volume:path> [<print_q_server/print_queue>]

It is probably easier to use a batch file to start the program, as the first parameter should not change, and the second should only change occasionally (as you want to be sure where the printouts end up). A batch file named go.bat is included. Please edit the first parameter to the program to reflect the set-up that you are using.

On startup, status messages will be printed out, informing you of the state as the program attempts to make sense of your parameters, and open the database files. Then the screen will be redrawn into a format with the cursor waiting for the username to be input. 

If the username does not exist in the current database, the program will prompt you is you wish to add it. Reply Y or N to the prompt, and if the answer is Y, then you will be prompted for the name of the server that the person has an account on. The program will then attach to the file server, and search the bindery for the user. If found, the user will be automatically added to the database, and the balance set to 0. The credit limit6 will also be set to 0 and the users full name as detailed in the bindery will also be added.

Then the users full name and account balance will be detailed on the screen and a transaction code will be prompted for. Valid transaction codes are D for Debit (ie subtract), C for Credit (ie Add), and P for printout activity7.

If C(redit) or D(ebit) is entered, the application will prompt for an amount to be entered (with no decimal points or other formatting). Once this is entered and ENTER is pressed, the program will strat a btrieve transaction, lock the relevant record in the account table, and update the balance.

If P(rintout) is selected, the application will send a summary of all the history records in the history table to the chosen printer8.

If S(how) is selected, the users history will be shown on screen a page at a time, in a similar format to the printout option.

Database Access
The print server object needs to have trustee rights to the directory where the btrieve database files reside. This is done with the strust.exe program provided in the archive file. The program is simple to use and can be done so by any supervisor equivalent user, by typing the line

strust <print server> <volume:path>

where <print server> is the name of the print server object
and <volume:path> is the name of the volume and path that the print server is to be made a trustee of.

Printer Types
Postscript
Postscript accounting is supported as of version 2.00 of the print server, and is only supported on directly connected serial lines. This is because of the need for the program to communicate with the printer to receive status messages etc over a bidirectional link. Bidirectional parallel printers are not supported and neither is appletalk.

The postscript printers also have the option of a user definable banner9. This banner may be of any format, and any number of pages, but is limited to be less that 4000 bytes long. It will get the relevant information about the print from the stack. The stacked items are in order of pushing (ie bottom to top)

		Parameter	Description
		1	Username to be printer in large type
		2	Job name to be printed in large type10
		3	The $ amount of the print job
		4	Number of pages in the print job 
		5	Cost per page for printing
		6	User Balance
		7	Credit Limit
		8	The time in hh:mm:ss format
		9	The date in dd-mmm-yyyy format
		10	The print job description
		11	The file server name
		12	The queue file name to be printed in small type.		13	The name of the queue
		14	The client connection number
		15	The user name printed in small type at the top of the banner

figure {seq figure|4}, Postscript printjob banner page parameters.

The locations and even whether the string is printed is entirely up to the person designing the banner, but don't forget to leave the stack empty (of these 15 parameters only) at the end of the job

Paintjet
Paintjet and Deskjet printers differ from the Laserjet series in a couple of small but very important aspects. Number one, they do not as supplied support the multiple page command, so this must be ignored during processing, unless the printer has an HPGL cartridge installed. The Paintjet and Laserjet options are identical apart from this small point. If you have a Paintjet or Deskjet that has the memory to support multiple pages, then the printer should be defined as Laserjet

Laserjet Series II
The Laserjet series II family is programmed with the PCL Level IV escape codes, and these are interpreted by the print server to calculate the number of pages to charge the user. Extended PCL IV commands such as pen colour are also interpreted, and passed straight through to the printer without error.

Laserjet Series III
PCL Level V was introduced with the Laserjet III series of printer, and as of yet the print server does not support the added escape codes and modes of the PCL Level V command set. It may be possible to add these at a later time when I have a printer and manual to develop the added features on.

NOTE: The print server does not support draft text printing with the auto wrap feature turned on for laserjet accounting.

Generic
The generic printer option is for the connection of any printer not supported, or for printers that are to be connected, but not charged for. This option performs no accounting and simply transfers the print job, character by character to the output port to be printed. A banner page may or may not be printed.

This option does not support postscript printers, as the banner is output as plain text, not as a postscript program.


Charon Compatibility
The print server program will also charge correctly for print jobs generated by the charon lpd gateway. All print jobs created on the netware server by the charon gateway will be owned, not by the user who queued the job, but by the charon print server object.

Luckily though, the charon gateway puts the owner and host name in the job description field. If the owner of a print job is not a user object, the print server will parse the job description field of the job, for the user name in front of the hostname. It will then use this name as the username on the current host. A side effect of this is that all users must have the same username on both systems. If the user is unknown still, the print job will be thrown away and not printed.

Serial Communications
For serial communications between the program and the printer, the program expects only a 3 wire connection (ie TXD,RXD and GND). The interface is interrupt driven and so should not lose any XON-XOFF sequence, although robust XON is recommended if available in case of line noise. The server will automatically come up with the serial lines as on-line, and will change state when an appropriate XOFF character is received on the serial line. If no serial printer is connected or the printer is turned off, the print job will be lost, as the print server will be unable to detect that the printer is not there.

Because of the nature of postscript printers, and the fact that they will communicate their status over the serial port, these printers will not lose the print jobs, but will time out from waiting and cycle with a timeout message on the screen. When the postscript printer is re-connected, the print server will automatically restart the output and continue counting pages.

Parallel Communications
The parallel communication is standard one way, 25 pin centronics standard. No information is received on the parallel port from the printer, the only status being provided from the printer by the standard status lines connected on the parallel port.

All output to the printer via the parallel port is polled, due to the sometimes unreliable nature of the parallel port interrupts. Interrupt driven Parallel port I/O, however may become an option in a later version.


The Screen

Accounting Method
There are now 2 methods of accounting with the accounting print server. There is the standard Novell Accounting calls with are available on versions of netware 2.1 and greater, or the newer Btrieve accounting, which needs access to a directory on a btrieve server

The users balance must be in credit before the job starts, or have unlimited credit, and the user must have enough money in his account to cover the price of the first page. No effort is made to charge the user per page until the entire job has been processed, with the result that a user may be able to go into overdraft. However once this happens, they may no longer print anything until they are in credit once more.

The units for accounting are unrelated to any monetary system, and like the disk charges can be any system you like, from dollars to cents, or any other system that has a base 10 following.

	eg 100 cents = 1 dollar etc

Updating Balances
The method of updating balances varies by the means of charging. With the novell accounting the balances may be updated by a user with supervisor privileges, by use of the syscon utility. With btrieve accounting the user balances may be updated with the utility provided, and only has to have minimal access to the databases used, to enable the reading and writing of the individual records. (See the btrieve section for details on updating balances with the btrieve accounting option enabled)

Step By Step Installation

1. For each file server to be connected to the print server.
	i. Add the printer server object with the pconsole utility. (Edit Print Servers menu option)
	ii. Add printer queues with the use of the netware pconsole utility.
	iii. Add the print server object to the print servers list of the selected print queues.
2. Edit the server.ini file to reflect the file server/print queue and connected printer set-up.
3. Edit the postscript banner file to reflect your particular desires for a banner page.
4. Select a machine to use as a print server with the correct hardware.
5. Generate a bootable disk with needed files on it.
6. Connect hardware to the print server.
7. Start the program!

New Program Features (by version)

	Version 1.0 
Original version
Single (ie 1:1) correspondence of input and output definitions.
Limited to the Parallel port only
Uses Novell Accounting functions
Accounting of HP-PCL Level IV printers

	Version 2.00a (not released)
Multiple input queues and servers per Output
Serial printers now supported

	Version 2.50 (Current Version)
Option of Btrieve accounting in addition to Novell Accounting
Support for Paintjet, Paintjet XL and Deskjet PCL printers added
Support for Postscript accounting with user definable banners
Compatible with charon generated print jobs


Bugs Fixed (By Version)

	Version 2.00a
1. Serial port code now works correctly.
2. All numeric values on banners now print correctly

Known Bugs (By Version)

	Version 1.0

1. The serial port outputs garbage to the printer. This limits the program to parallel output until this can be fixed. As this is only an Alpha release it is hoped that this will be fixed before the next update.
2. Negative print balances print  garbage value.

	Version 2.00a

No known bugs.

	Version 2.50

No known bugs.

Future Enhancements

Inclusion of Double Queueing, to allow many inputs be concentrated to one output. At the moment hardware outputs such as the Parallel and Serial ports have only a 1-1 relationship with the queues that are served.

Ability to change the set-up without taking the server down and editing the init file by hand.

Program statistics to be optionally displayed, instead of, or as well as the printer status, for each queue.

Ability to check the status of the queue, and estimate print times.

Direct IPX peer-peer communication between a controlling console running on a separate PC and the print server.

Conversion from a standalone program to an NLM or a VAP

Inclusion of lpd protocols to enable serving of TCP/IP hosts and queuing.
Btrieve Database Details

The btrieve database is set up with the help of 3 files. A batch file create.bat is run, and it uses the butil.exe utility, along with the 3 description files (history.dsc, server.dsc & accounts.dsc) to create the .dat files. The create.bat file should be modified to indicate the correct directory path for the creation of the database *.dat files.

The database tables themselves consist of the following fields (in C structure notation).

struct account {
 u_long accnum;         /* KEY account number, unique, auto */
 long   balance;        /*     balance of account */
 long   limit;          /*     lower limit of account */
 char   name[50];       /* KEY account name */
 char   fullname[50]    /*     full name of account */
};

struct server {
 u_long servnum;        /* KEY server number, unique, auto */
 char   servername[50]; /* KEY server name as advertised */
};

struct history {
 u_long accnum;         /* KEY account number */
 u_long pages;          /*     number of pages printed */
 u_char time_date[6];   /*     time & date in qms1 format */
 u_long cp_page;        /*     cost per page */
 u_long balance;        /*     remaining balance */
 u_long servnum;        /*     server number */
 long   queueid;        /*     objid of queue */
 char   transaction;    /*     transaction code */
};
figure {seq figure|4}, Database table structure definitions.


figure {seq figure|5}, Relationship diagram of the 3 btrieve data tables

The previous diagram outlines how the 3 database tables user, server and account relate to each other. The fourth table, is a timed record of each transaction that occurs within the database. The applications that access the tables, should perform record locking on any tables that are to be changed, to negate the risk of a lost update occurring. Btrieve should also be installed to support transactional tables, as this will negate any risk of lost or (worse) partial update due to power-failure or machine lockup.


History Transaction Codes

/* transaction codes */
#define ACC_CREDIT           'C' /* ie money payed */
#define ACC_DEBIT            'D' /* ie money withdrawn */
#define ACC_LIMIT            'L' /* Change of limit */
#define ACC_AUTOC            'A' /* Page Printed Charge */
#define ACC_NEW              'N' /* New account created */
#define ACC_PRINTOUT         'P' /* Printout of account */


These are the transaction codes as used in the current version of the print server. They are pretty much self explanatary, with Credit Debit etc. No history is recorded at present for printouts, the code is simply present for completeness.
1COM3 and COM4 have not as yet been fully tested, and they will share the interrupts with COM1 and COM2 as per IBM PC/AT standards.
2Laserjet Series III with PCL Level V are not yet supported, and will be treated as laserjet series II printers with PCL Level IV
3HPGL is not yet supported, and as it is a part of PCL Level V, will be introduced at the same time as the series III printers are supported fully. Currently mapped to the generic printer interface
4BREQUEST, the novell btrieve redirector must also be loaded at the workstation that is being used for the print server.
5The program strust.exe may be used to enable the print server object to have all access to the btrieve database directory.
6At this stage the credit limit is set to 0 and cannot be changed by this program. If changed however, by other means, the program will not attempt to reset it, and will honour the new credit limit.
7Please see the section at the end of this document for a complete list of transaction codes available in the history table. If new transaction codes are neede by people writing applications for this database, please register them with me so that the tables can always be consistent.
8The summary sent to the printer will not include any printout records, as these may be skipped over as purely informational. However if there is a need to charge for the printout service (as many banks do for statements of account), then this may be easily implemented and the printout  changed to reflect this.
9The user defined banner is the same for all postscript printers and can not of yet be varied between different printer outputs. If the banner file BANNER.DPS does not exist a standard default banner will be used instead.
10The job name is taken from offset 45 in the clientRecordArea of the job. Utilities such as nprint fill this in with the file name and it is referred to as the banner name under pconsole
1QMS date format is a 6 byte field where the bytes represent YMDHMS


{PAGE|ii}





{PAGE|12}

Appendix A-{PAGE|ii}


