Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PROGRAMS / UTILS / MOUSE / VSPOOL01.ZIP / SPOOL.DOC next >

Wrap

Text File | 1989-03-20 | 29.0 KB | 859 lines

Table of Contents 1. Overview...................................................2 2. Installation...............................................2 3. Accessing Versa-Spool Once Installed.......................3 4. The Parameters Enumerated..................................4 5. Examples...................................................7 5.1. To Install............................................8 5.2. After Installation....................................8 6. Programmer's Corner........................................9 6.1. Sub-Function 0 : Return Signature.....................9 6.2. Sub-Function 1 : Toggle Pause.........................9 6.3. Sub-Function 2 : Clear Buffer.........................9 6.4. Sub-Function 3 : Request Pause Condition..............9 6.5. Sub-Function 4 : Request Free Buffer Space............9 6.6. Sub-Function 5 : Request Total Buffer Size............9 6.7. Sub-Function 6 : Redirect Output To LPT1:.............9 6.8. Sub-Function 7 : Redirect Output To LPT2:.............9 6.9. Sub-Function 8 : Redirect Output To LPT3:.............9 6.10. Sub-Function 9 : Request Output Device..............10 6.11. Sub-Function A : Request Output Speed...............10 6.12. Sub-Function B : Request Device Spooled Status......10 6.13. Turbo Basic Function Call Examples..................10 7. Business Stuff............................................10 8. User Registration Form....................................12 i Versa-Spool Version 1.01 A multi-printer spooler Copyright 1989 - Jeff Newbro 1 1. Overview Versa-Spool is an extremely versatile print spooler written for the IBM-PC/AT series of computers. In an effort to anticipate all the circumstances under which Versa-Spool may be required to operate, features such as multiple buffers, large buffer size, adjustable output speed, and the ability to redirect a printer stream from one printer to another have been implemented. A protocol has been developed which will permit access to the operating parameters and current status of Versa-Spool either from the dos prompt, or from within a program in order to enable applications to interact intelligently with their printer resources. Versa-Spool is installed and accessed at the dos prompt with the following syntax : SPOOL [-option(s)] <enter> where option is one or more of the following : -b{n} = Buffer size (n=1..Available memory in k) -c = Clear print buffer -n{n} = printer Number (n=1..3) -p = toggle Pause -r{n} = Redirect output to new device (n=1..3) -s{n} = output Speed in cps (default = 100) -u{n} = allocate buffers in Unused memory (n=0..FFFF) -v{n} = offset interrupt Vectors (n=1..6) -? = Show status 2. Installation Versa-Spool is a memory resident program which installs itself according to parameters specified by the -b, -n, -s, -u, and -v options the first time it is executed. If no value is specified for these options, Versa-Spool will assume that 1 buffer, 1 kilobyte, and 100 characters per second, are the desired parameters. For example, to install Versa-Spool to provide LPT1: and LPT2: with 80k buffers each, the following command line would be entered : C:\> spool -n2 -b80 <Enter> or, for a single 200k buffer for LPT1:, type : C:\> spool -n1 -b200 <Enter> It would not be possible to install a single buffer for LPT2:, since the buffers are allocated sequentially, beginning with 2 LPT1:. It would, however, be possible to install a single buffer for LPT1: whose output was redirected to LPT2:. This would be accomplished by the following two commands : C:\> spool -n1 -b100 <Enter> C:\> spool -n1 -r2 <Enter> The redirection feature will be discussed in greater detail later. Once Versa-Spool has installed itself as a terminate and stay resident program (TSR for short), it will print its installation status on the screen and return to dos. For those who may want to install Versa-Spool with a batch files that checks the success of its commands, an error level of 0 will be returned if the installation was successful, or 1 if there was an error. Also, for the batch file programmers, the messages printed on the screen by Versa-Spool may be piped to the nul device if it is undesirable for the end user to see them. For instance a batch file containing the lines : . . spool -n1 -b100 > nul IF ERRORLEVEL 1 GOTO NOGOOD . . would install a 100k buffer for LPT1: and show no message after installation. If Versa-Spool did not install itself properly, execution would be vectored to the label "NOGOOD", presumably to echo an error message and exit. Subsequent executions of Versa-Spool will not install another TSR copy of Versa-Spool, but will rather provide communication with the already installed TSR program. The protocol for this communication is described in the "Programmer's Corner" section. 3. Accessing Versa-Spool Once Installed After the first time Versa-Spool is run, and its TSR portion is loaded, subsequent executions of the program will either cause it to print the current status of the resident copy in response to the -? option, or attempt to modify its operating status according to the -c, -p, or -r parameters. For example, if LPT2: is to be paused for some reason, the line : C:\> spool -n2 -p <Enter> would be entered. Note that in this instance, the -n parameter 3 specifies the device to be addressed, rather than the number of buffers to be installed. This convention applies to all executions of Versa-Spool subsequent to the first, when it installs its TSR portion. The pause option is a toggle, so to restart the printer, the same line would be re-entered. Similarly, to clear the buffer for LPT1:, the line : C:\> spool -n1 -c <Enter> will effect the desired result. Or, since -n1 is a default value, simply : C:\> spool -c <Enter> would suffice. 4. The Parameters Enumerated Now that you have the general idea, here is some more specific information about the available parameters. -b This parameter is only available when installing Versa- Spool. Most currently available spoolers are limited to 64k, but Versa-Spool permits buffer sizes between 1k and the maximum available memory in your machine (less 64k) to be installed. When allocating buffers with the -u parameter, the buffer size is restricted by other factors which will be discussed later, but in most situations the previously stated rule applies. During installation, the default value for this parameter is 1k, and after installation, it cannot be used to modify the TSR portion of Versa-Spool. -c The buffer selected by the -n parameter will be cleared. Any other buffers which have been allocated will continue to function without disturbance. A typical command line would be : C:\> spool -n2 -c which would clear the contents of the buffer for LPT2:. This parameter has does not function during installation, but the clearing of a buffer is implicit in the process of its creation. -n During installation, the -n option specifies the number of buffers that will be allocated. Each will be the same size, as specified by the -b option, and will be assigned sequentially to LPT1:, LPT2: and LPT3:. Thus, it is not possible to assign a buffer for LPT2: without 4 first assigning one for LPT1:. Once the resident portion of Versa-Spool is installed, the -n parameter will serve to specify the buffer to which any commands will apply. For instance, in order to request the status of the buffer for LPT3:, the following line would be typed : C:\> spool -n3 -? When the -n parameter is not specified, either 1 buffer, or LPT1: will be assumed during installation or subsequent operations, respectively. -p Once Versa-Spool is installed, a printer may be paused, if that is desirable. The -p option, which effects this action, is a "toggle" and invoking it will cause a printing device to pause, or a paused device to resume printing. -r Once installed, the output from the spooler may be redirected from its normal device to another LPT: through the use of this parameter. Thus, if you had a dot-matrix printer attached to LPT1:, and a letter quality printer attached to LPT2:, and a word processor that only printed to LPT1:, you could redirect the word processor output to LPT2: through the use of this option. The command line for that specific situation would be : C:\> spool -n1 -r2 <Enter> Also, in database applications where printer speed is a problem because large reports are generated regularly, Versa-Spool may be used to divide the output between two or three printers to afford an effective output rate of two or three times that possible with a single, unspooled printer. The -r option is only available after the resident portion of Versa-Spool has been installed, and has no effect during installation. -s The output speed parameter determines the efficiency of Versa-Spool for the environment in which it is being used. Since Versa-Spool shares the computer's attention with the currently running application, there is a compromise between the rate at which it sends data to the printer(s), and the rate at which it permits the currently running application to perform its functions. Outputting data to the printer at a rate faster than either the computer can process it, or the printer can accept it will result in Versa-Spool hogging the 5 computer's time to no advantage, and causing the application program to seem unresponsive. Outputting too slowly, of course will cause large documents to take excessive amounts of time to print. Since the circumstances under which Versa-Spool may be expected to vary widely, this parameter has been made accessible to the user. This parameter is adjustable from 20 to 16000 characters per second, in increments of 20 cps. It will be some time before hardware is available that will accommodate the higher speeds, but Versa-Spool will be ready when the time comes. -u Although dos was only written to accommodate 640k of main memory, many machines are currently being produced which permit 1000k (1 megabyte) to be installed on their motherboards. The additional 360k of memory, beginning at hex segment A000 is partially allocated to video board RAM, extended memory buffers, and other such functions, but there is frequently 64k or more of contiguous space available in this area. With the -u option, Versa-Spool may be installed with its buffers allocated in this unused area, allowing large buffers to be implemented while taking up less than 30k of precious dos space. It is not recommended that the naive user try to install Versa-Spool in this configuration, but someone with light programming experience should be able to find between 64k and 192k of unused RAM in the range of segments C000 to F000 in one of these 1 megabyte machines. Once found, Versa- Spool may be instructed to allocate its buffers starting at a given segment address by entering the -u parameter followed by the HEX address of the segment. Segment addresses of less that A000 will be adjusted upward to A000, and if Versa-Spool does not find RAM at the specified segment, an error message will be displayed and the resident portion will not be installed. A typical implementation of such a buffer would be : C:\> spool -n1 -b128 -uD000 <Enter> Just to make it a little easier for the stout at heart who decide to try this, there should be 64k available starting at E000 in nearly all of these machines and 128k starting at D000 in most without extended memory. It is worth checking below that area, but many hard disk controllers have a ROM starting at C800 which will interfere with the buffer. -? If it is desirable to know the status of one of the spooled printers, this parameter will instruct Versa- Spool to display a detailed report on the screen. This 6 information includes any redirection for the device, the output speed, buffer size, port status, pause status, and remaining free space. This function may also be useful to programmers, as it returns the remaining free space (in k) to dos as an error level when it executes. Thus it may be used in batch files to test for insufficient buffer space before running a program which generates large reports. An example from a batch file which does this follows : . . :START REM Get the free space in buffer 1 (send the REM display to nowhere) spool -n1 -? > nul REM If there is 10k or more of free space, print REM the next file IF errorlevel 10 GOTO PRINTDOC REM Do some word processing until the spooler REM is ready wordproc %2 :PRINTDOC REM Print the report specified by %1 printrep %1 :NEXT . . Of course, this option is only available once the resident portion of Versa-Spool is installed and has no effect during installation. -v Many TSR programs use one or more of the interrupts between 60h and 67h for their resident functions. So that the two interrupts required by Versa-Spool do not contend with any of the programs that you normally keep resident, you may install it with its vectors offset from the default 60h and 61h through the use of this parameter. The example command line : C:\> spool -n1 -v3 <Enter> would install Versa-Spool with its interrupts at 63h and 64h. This option is only available during installation, and will default to 0 if not specified. 5. Examples Here are a few more example command lines to help convey the 7 points expressed earlier. 5.1. To Install Command Configuration C:\> spool Show syntax for Versa-Spool but do not install. C:\> spool -N2 -B60 Install Versa-Spool with 60k 100cps buffers for LPT1: and LPT2:. C:\> spool -n1 -b350 Install a 350k, 100cps spooler for LPT1:. C:\> spool -n1 -b128 -uC800 Install a 128k, 100cps spooler for LPT1: with its buffer starting at hex segment C800. C:\> spool -s256 -n1 -s200 Install a 256k, 200cps spooler for LPT1:. 5.2. After Installation Command Effect C:\> spool -N1 -? Show the current status of LPT1: C:\> spool -n1 -c Clear the buffer for LPT1:. C:\> spool -P -N2 If LPT2: is printing, it will pause, otherwise, it will resume printing. C:\> spool -n1 -r2 Redirect the output of logical LPT1: to physical LPT2:. Note that the parameters are neither case-sensitive, nor required to be in any specific order. Thus, the lines : C:\> spool -n1 - C and C:\> spool -c -N1 are equivalent. Also, throughout the documentation, the prompt indicates that the current directory is C:\, although this is by 8 no means required for the proper operation of the program. 6. Programmer's Corner When Versa-Spool is installed, it changes the original interrupts 17h and 1Ch to 60h and 61h (plus an offset, if any), respectively, and installs its own interrupt handlers for 17h and 1Ch. The new interrupt 1Ch performs Versa-Spool's background functions and then passes control to the original interrupt 1Ch. The new interrupt 17h performs a reset (function 2) immediately by passing control to the original interrupt 17h. All other functions are buffered by Versa-Spool. The new interrupt 17h also has an additional function not provided by the original interrupt, which may be called from a high level program to request the spooler status or control the operation of the spooler. The additional function and its sub-functions are implemented as follows : In all cases : Interrupt = 17h AH = 3 ( Function # ) AL = Sub-Function # ( Sub-Function # ) DX = Device # (0..2) ( LPT1:..LPT3: ) 6.1. Sub-Function 0 : Return Signature Return Value : AX = 1234 if Versa-Spool is installed, undefined if not installed. 6.2. Sub-Function 1 : Toggle Pause Return Value : AX = 1 if paused, 0 if resumed. 6.3. Sub-Function 2 : Clear Buffer Return Value : AX = 0 if cleared, 302h if not. 6.4. Sub-Function 3 : Request Pause Condition Return Value : AX = 1 if paused, 0 if resumed. 6.5. Sub-Function 4 : Request Free Buffer Space Return Value : AX = Remaining Buffer Space (in Kbytes). 6.6. Sub-Function 5 : Request Total Buffer Size Return Value : AX = Total Buffer Size (in Kbytes). 6.7. Sub-Function 6 : Redirect Output To LPT1: Return Value : none. 6.8. Sub-Function 7 : Redirect Output To LPT2: Return Value : none. 6.9. Sub-Function 8 : Redirect Output To LPT3: Return Value : none. 9 6.10. Sub-Function 9 : Request Output Device Return Value : AX = Output Device To Which Selected Device is printing (0..2). 6.11. Sub-Function A : Request Output Speed Return Value : AX = Output Speed in Characters per second. 6.12. Sub-Function B : Request Device Spooled Status Return Value : AX = 1 if device is spooled, 0 otherwise. 6.13. Turbo Basic Function Call Examples The following Turbo Basic1 code will illustrate the use of some of the previous functions. The same principles exemplified here will apply to all languages that permit interrupt calls. . . REG 1, &H304 ' AH = 3 AL = 4 (Function 3, Sub- ' Function 4) REG 4, &H0 ' DX = 0 (LPT:1) CALL INTERRUPT &H17 ' Call the interrupt PRINT "The buffer for LPT1: has ";REG(1);"k free" REG 1, &H304 ' AX = 304h REG 4, &H1 ' DX = 1 (LPT:2) CALL INTERRUPT &H17 ' Call the interrupt PRINT "The buffer for LPT2: has ";REG(1);"k free" REG 1, &H307 ' AX = 307h REG 4, &H0 ' DX = 0 CALL INTERRUPT &H17 ' Call the interrupt PRINT "The data sent to LPT1: will now be output to LPT2:" . . 7. Business Stuff This program is distributed under the ShareWare concept. Under this philosophy you may run the program for the purpose of evaluation for a reasonable period of time without incurring any liability either to purchase a license or be held responsible for any copyright violations. If you decide that the program does suit your purposes, however, you are obliged to purchase a license to use it and pay a registration fee. When you register your program, you will receive your own serialized copy which -------------------- 1. Turbo Basic is a registered trademark of Borland International 10 will probably earn you money, since a commission of 25% is paid to the licensee whose serial number appears on each registration form received. Thus, if you upload your copy to a bulletin board and five people download it and register as licensees, you will not only have acted in good faith, but made money for having done so. These commissions are paid at the end of each month. Now that your interests are protected, the license to use Versa- Spool is issued subject to the conditions specified on the registration form, which protect mine. Thank you for your interest in Versa-Spool and I hope you enjoy using it as much as I enjoyed writing it for you. 11 8. User Registration Form Licensing Conditions No warranty is either expressed or implied with regard to Versa- Spool. The user has more than ample opportunity to evaluate the performance of the program under normal operating conditions, and the author cannot be expected to bear the consequences of an improper evaluation. Further, the author will be held blameless for any and all damages arising from the use of Versa-Spool, be they direct or consequential. Name :______________________________________________________ Title :_____________________________________________________ Company :___________________________________________________ Address :___________________________________________________ City,State,Zip :____________________________________________ Business Telephone :________________________________________ Serial number of evaluation Versa-Spool :___________________ Where did you obtain the evaluation copy ? (BBS, Consultant, Magazine, other) : _______________________ I have read and agree to the terms of the license agreement : ________________________________________________ ___/___/___ (Signature) (Date) Comments or suggestions :___________________________________ ____________________________________________________________ ____________________________________________________________ Please complete the above form and send it with your check or money order for $20 (plus appropriate sales tax in MA) to : Jeff Newbro 267 Lexington Street East Boston, MA 02128 Assigned Serial # :_________________________ (For office Use) 12