Received: from j.cc.purdue.edu by VM.CC.PURDUE.EDU ; Mon, 13 Jun 88 08:03:03 EST Received: by j.cc.purdue.edu (5.54/1.14) id AA01037; Mon, 13 Jun 88 08:00:37 EST Date: Mon, 13 Jun 88 08:00:37 EST From: ain@j.cc.purdue.edu (Patrick White) Message-Id: <8806131300.AA01037@j.cc.purdue.edu> To: fys-ma@fintuvm.BITNET Subject: comp.binaries.amiga, comp.sources.amiga: sources/amiga/volume5/printspool.d.sh binaries/amiga/volume6/printspool.d.sh Newsgroups: comp.binaries.amiga, comp.sources.amiga Subject: printspool (docs) Keywords: print spooler, printspool, docs Approved: ain@j.cc.purdue.edu (Patrick White) Program Name: printspool (docs) Submitted by: gagnon@larry.mcrcim.mcgill.edu (Francois Gagnon) Summary: A printer spooler. Poster Boy: Patrick White (ain@j.cc.purdue.edu) Archive Name: sources/amiga/volume5/printspool.d.sh.Z binaries/amiga/volume6/printspool.d.sh.Z Tested. NOTES: I redid the binaries shar to extract the docs, but didn't touch the sources shar. -- Pat White (co-moderator comp.sources/binaries.amiga) ARPA/UUCP: j.cc.purdue.edu!ain BITNET: PATWHITE@PURCCVM PHONE: (317) 743-8421 U.S. Mail: 320 Brown St. apt. 406, West Lafayette, IN 47906 [How do you get to heaven? Go to Pluto and hang a left.] ======================================== # This is a shell archive. # Remove everything above and including the cut line. # Then run the rest of the file through sh. #----cut here-----cut here-----cut here-----cut here----# #!/bin/sh # shar: Shell Archiver # Run the following text with /bin/sh to create: # Print_Spool.doc # Print.hlp # Tabs.dat # This archive created: Fri Jun 3 13:20:36 1988 # By: Patrick White (PUCC Land, USA) echo shar: extracting Print_Spool.doc '(18032 characters)' cat << \SHAR_EOF > Print_Spool.doc Print_Spool.doc V1.0.0 27-Mar-1988 ) Frangois Gagnon Contents 1. Copyright Notice 2. Introduction 3. Technical Support 4. Spool Program Startup 5. Spool Program Execution 6. Print Program Operation 6.1 Action Requests 6.2 File Requests 6.3 Printing Options 7. Print and Spool Error Messages 7.1 Spool Internal Errors 7.2 Print Internal Errors 7.3 Print External Errors 8. Restrictions and Improvements 9. Character Tabulation [1m1. Copyright Notice[0m Copyright ) 1988 Frangois Gagnon, All Rights Reserved. The author does not make any warranty expressed or implied, or assumes any liability or responsiblity for the use of this software. Permission is hereby granted to copy, reproduce, redistribute or otherwise use this software as long as it is for non-profit. This notice and the above copyright notice must remain intact and appear on all copies. Permission is also granted to correct any problems with this software, but modifications and improvements are reserved by the author. [1m2. Introduction[0m The purpose of the Print_Spool package is to provide the Amiga with a printer spooler for ASCII files. It is made of two programs working in a master-slave relationship. The Print program is the master and is called by the user whenever he wants to interact with the spooler. The Spool program is the slave and executes in the background printing files and awaiting the masters requests. The Spool program provides two major facilities to the user. The first one is the handling of a printing queue which is used to schedule multiple files in advance. The second one is the ability to specify individual printing characteristics for each file. These include the paper format, character type and size to use and the ability to add page headers and line numbers to the file. [1m3. Technical Support[0m I will be happy to receive any comments you may have on the behaviors and the performances of both programs. Any improvements will be evaluated according to their complexity, their usefulness to all users, the available time and my own needs of the programs. If other programmers want to include an interface in their public domain program with the Spool program, it will become an asset to the Amiga community. Frangois Gagnon 668 Paul VI Terrbonne, Quebec J6W 1W1, Canada Usenet: gagnon@zap.uucp or gagnon@cae.uucp [1m4. Spool Program Startup[0m Although the Spool program can be started at any time, it is suggested that it be started in your Startup-Sequence. The program does not tie any resources except memory while it has no file to print. This makes it a suitable memory resident program. This program as only one argument which is the name of the file to use for logging the printing operation. The default is a file called RAM:Spool.log but could be any valid file that can be opened in "append" mode including NIL:. > run Spool RAM:Spool.log The log file does not remain opened while the program is running, instead it is opened in "append" mode every time there is an information to add. This allows the user to look at file as needed and even to delete it if it becomes to large. The Spool program looks at the preference information for some initial values. These only include the paper formats: (refer to the CHANGE request) narrow (8 inches) <--> wide (13 inches) short (8.5 inches) <--> long (11 inches) [1m5. Spool Program Execution[0m The Spool program follows a finite automaton to perform its operation. This means that the program can only be in a finite number of state during all of its execution (see the REPORT request). You should refer to the source code of the Spool program for more details on the relationship between the states and the requests. Spool: Waiting for a file to print. While in this state, the printing queue is empty and the program is waiting for an INSERT request which will specify a new file to print. In the mean time, the printer device can be used by other program. Spool: Waiting for a change of paper. The Spool program goes into this state when the paper format for the next file to print does not match the one currently in the printer. Upon startup, the program expect the paper in the printer to be of the format specified in prerefence. The Spool program must be notify using the CHANGE request when the paper matches the format required by the next file. Spool: Waiting to access the printer. The Spool program goes into this state when the printer is not available to print a new file. This usualy means that the printer is being used by another program. The Spool program will retry every 5 seconds until it succeeds. Spool: Printing a requested file. While in this state, the program is printing one of the requested files. The printing options used throught the file are the ones specified when it started to print the file. Those options could be changed for the current file using the UPDATE request but will only be used for the following copies, if there some left to do for the file. Spool: Printing but will pause after the file. While in this state, the program is also printing one of the requested files. The rules of the previous state still apply but the Spool program will suspend itself after the current copy of a file is printed. Spool: Pausing between two files. While in this state, the Spool program is suspended and is waiting for a RESUME request to start printing a new file if there is one. The printer device is available for use by other programs. Spool: Pausing in the middle of a file. The Spool program goes into this state when a FREEZE request is received and it is currently printing a file. The access to the printer device is still active but no new data is sent. The printer will normally empty its own buffer before truly stopping. The Spool program can be resumed using the RESUME or the FINISH request. [1m6. Print Program Operation[0m The Print program can be used at any time and even multiple time simultaneously. Its purpose it to analyze the command line for arguments, send the corresponding requests to the Spool program, wait for the results, and display them to the user. There are two types of arguments in a command line. A command always starts with the minus sign while all other arguments are file specifiers. Lower case and upper case are equivalent for all arguments and abbreviation are accepted in command names. The '?' and '*' are the only wild character accepted by the program but there is a maximum of ten '*' per file specifier. There are three kinds of commands supported by the Print program. The first group are requests that will be immediately executed by the Spool program. The second group define the operation to perform when a file specifiers appear on the command line. The last group are commands which modifies the options that are used by the Spool program to print a file. If no argument appears on the command line, the REPORT request will be automatically executed. The two following command lines are equivalent. > Print > Print -report [1m6.1 Action Requests[0m The following commands are used to control the Spool program activity. -report This command requests that the status of Spool program and the contents of print queue be displayed on the screen. The options of the files are included in the list. -return This command resquests that the flag telling the Spool program if it must terminate be toggled. The program only terminates when there are no more files to print and the flag is set. The program will continue to accept requests until it does terminate. -change This command tells the Spool program that the paper format on the printer matches the requirements of the next file in the queue. -freeze This command requests that the Spool program suspends its activity even if it is currently printing a file. All the internal information are preserved allowing the printing to be resumed from the point it was frozen. -finish This command requests that the Spool program suspends its activity after it finishes printing the current file. The operation will be immediate if it is not printing a file. This request is useful if you need to use the printer for some other activity. -reset This command requests that the Spool program stops printing the current file but does not record it as printed. The Spool program will also become suspended awaiting new requests. This request is useful if you did not properly set the option before asking it to print a file. Yous can update the option and then resume the printing. -cancel This command requests that the Spool program stops printing the current file and does record it as printed. The Spool program will also become suspended awaiting new requests. -resume This command requests that the Spool program resumes its activity after being suspended by one of the previous requests. [1m6.2 File Requests[0m If none of these three commands appear on the command line before a file specifier is used, the INSERT request will be used automatically. The two following commands are equivalent. > Print *.c > Print -insert *.c -insert For every file specifier following this command, the specified directory is searched for matching files. The resulting file list is sent to the Spool program for insertion at the end of the queue. The options used for all files of a specifier are the ones current when the specifier is encountered on the line. > Print -insert Print.hlp -update For every file specifier following this command, the specified directory is searched for matching files. The resulting file list is sent to the Spool program to be used as a search list for updating the queue. The list is then reported back with a flag indicating if the file was found in the queue. The new options used for all files of a specifier are the ones current when the specifier is encountered on the line. > Print -update -2 *.h -cpi12 -1 *.c -remove For every file specifier following this command, the file specifier is sent as is to the Spool program. It is used as a pattern to search the queue for matching files which are immediately removed and reported back to the user. > Print -remove *.h *Print_Spool/* [1m6.3 Printing Options[0m The initial values of most of the printing options are extracted from the preference information. They include paper formats, text density and text style. All other initial values are hardcoded in the Print program. These options remain effective for the duration of the Print program execution or until they are changed by other commands. All of the option apply to a complete file but your file may contain printer commands. However, it is not recommanded that the page length or the line density be changed. -cpi10 -cpi12 -cpi17 These three commands allow you to specify the character density. The number indicates the number of character per inch on a line. -lpi6 -lpi8 These two commands allow you to specify the line density. The number indicates the number of lines per inch on a page. -narrow -wide These two commands allow you to specify the width of the required paper. Before starting to print a file, those values are verified (see the CHANGE request). You can select between 8 inches and 13 inches. -short -long These two commands allow you to specify the length of the required paper. Before starting to print a file, those values are verified (see the CHANGE request). You can select between 8.5 inches and 11 inches. -draft -letter These two commands allow you to specify the character quality to use for printing the file. -header This command controls a toggle which indicates if the Spool program must add page headers to the file. The header comtains the date the file was created, the full name of the file and the current page number. The headers are added by default. -number This command controls a toggle which indicates if the Spool program must add line numbers to the file. This field is exactly 8 characters to preserve the tabulation. The numbers are added by default. -#### This command is used to indicate the number of copies to print of a file. The #### represents the number you type in and obviously the minus sign is not part of the number. A value of zero is valid and cause the file not to be printed when its turn comes. -keep -delete These two commands allow you to specify what to do with the file when the last copy has been printed. The file will be kept by default. [1m7. Print and Spool Error Messages[0m This section describes all the possible error messages from both programs. The reason and a solution are also given when possible. [1m7.1 Spool Internal Errors[0m Spool: Unable to access log file. This message means that the Spool program could not access the specified log file. The file name could be illegal or the media could be of wrong type or write protected. Spool: Spool is already running. This message means that another copy of the Spool program is already executing or more precisely that a port already exists with the Spool program communication port name. Spool: Unable to create a port. This message means that the Spool program could not create the required communication port. Verify if you are not running out of memory. [1m7.2 Print Internal Errors[0m Print: Unable to find Spool port. This message means that the Print program could not access the Spool program communication port. Usually, it means that the Spool program is not currently running and need to be started. It could also mean that the Print program was used to soon after starting up the Spool program. Print: Mismatched protocol versions. This message means the Print and the Spool program do not use the same version of the communication protocol. Verify if you use the most recent version of both programs. Print: Unable to create Print port. This message means that the Print program could not create the port that will be used to receive the results of the requests. Verify if you are not running out of memory. Print: Unable to allocate memory. This message means that you are running out of memory. [1m7.3 Print External Errors[0m Print: Unknown or ambiguous command = This message means that the specified command is unknown to the Print program. Verify the spelling and the list of commands or supply more characters. Print: File not found = This message means that the specified file could not be found. Verify the spelling and the specified path. Print: Wrong file type = This message means that the specified file is a directory and is not suitable for printing. If you want to print the contents of a directory, execute you favorite directory command and send the result to the RAM disk. Then use the print command with the DELETE option and the file will be deleted as soon as it is printed. Print: File name too long = This message means that the resulting full file name is too long for the internal buffer. You will have to rename the file or directory names in the path to reduce the resulting length. [1m8. Restrictions and Improvements[0m The protocol between the two programs restricts the full name of a file to 96 characters but only 42 can appear on a page header. This could be changed by adding a second line in the header for the file name if many users request it. The Spool program does not currently use full asynchronous operation with the file system and the printer device. This means that the program can only check the communication port between printing lines. Delays in response time for the Print program could be introduced by the Spool program and the file system. The Spool program does not execute as a completely independant process. This means that the program still keeps the three default files (stdin, stdout and stderr) opened as provided by the process that starts the program. There is new "detach" declaration provided with MANX 3.6a which I will probably investigate. The full file name is used internally to specify a file to be printed. The file can be deleted or replaced without the Spool program knowing it (this only applies if the program is not currently printing that file). If the file is replaced, the size that is displayed for information and the date that appears in the page header will be invalid. The Print program does not currently have a Workbench interface. I will welcome all well designed and well written programs that would provide such an interface to the Spool program. The Print and the Spool programs can be used as reference for the complete definition of the protocol. [1m9. Character Tabulation[0m Some printers do not set the default tabulation to every eight columns. If yours does not, you may have some problems printing file that contains such character. If you are not sure about your printer, you can verify using the "Tabs.dat" file provided with this package. The last two lines of the file should printout identical if the tabs are properly set. You can simply use one the following commands to test your printer alone. > copy Tabs.dat par: > copy Tabs.dat ser: You should also print the file using the Print and Spool programs to make sure the tabs are properly initialized by the printer driver. (This only works if the file has not been modify by any communication programs) > run Spool > wait 5 > Print -header -number Tabs.dat The Spool program currently sends the "aTBSALL" printer commands to set the default tabs. If that does not work for you, you will have to modify the Spool program at the place that it initializes the printer. SHAR_EOF if test 18032 -ne "`wc -c Print_Spool.doc`" then echo shar: error transmitting Print_Spool.doc '(should have been 18032 characters)' fi echo shar: extracting Print.hlp '(912 characters)' cat << \SHAR_EOF > Print.hlp Print.hlp V1.0.0 27-Mar-1988 ) Frangois Gagnon * ? = Pattern matching characters -cpi10 -cpi12 -cpi17 = Characters per inch -lpi6 -lpi8 = Lines per inch -narrow -wide = Width of the paper -short -long = Length of the paper -draft -letter = Character quality -header = Toggle for page headers -number = Toggle for line numbers -#### = Number of copies -keep -delete = File completion facility -insert -update -remove = Operation on file specifier -report = Report spooler status -return = Spooler must terminate -change = The paper format was changed -freeze = Suspend immediately -finish = Suspend after the file -reset = Suspend to restart the file -cancel = Suspend and cancel the file -resume = Resume the printing operation SHAR_EOF if test 912 -ne "`wc -c Print.hlp`" then echo shar: error transmitting Print.hlp '(should have been 912 characters)' fi echo shar: extracting Tabs.dat '(255 characters)' cat << \SHAR_EOF > Tabs.dat 1 2 3 4 5 6 7 8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 X X X X X X X X X X X X X X X X X X SHAR_EOF if test 255 -ne "`wc -c Tabs.dat`" then echo shar: error transmitting Tabs.dat '(should have been 255 characters)' fi # End of shell archive exit 0