Category : Pascal Source Code
Archive   : SPOOL100.ZIP
Filename : SPOOLER.DOC

SPOOLER ver. 1.0 del 21/04/90

Paolo Ruggieri - Genova

Una unit di PUBBLICO DOMINIO per accedere
ai servizi di PRINT.COM (spooler MS-DOS)
dai programmi in TurboPascal 4.0 o successivi.

Per commenti, suggerimenti e segnalazioni di bugs sono raggiungibile
via modem presso:

Utente MC4479 su MC-Link (300/1200/2400 baud, 8-N-1
06-4510211/4513182/4180440
NUA Itapac 26500140)

o attraverso l'area (echo Italia) TurboPascal presso
vari BBS della rete Fido.
==============================================================================
Con passare delle versioni MS-DOS e` diventato sempre piu` "ingombrante",
in termini di memoria di massa e RAM occupate; a questo aumento di occupazione
e` corrisposto un aumento di affidabilita`, velocita` e di funzionalita`
soprattutto attraverso l'introduzione di nuove utility (comandi esterni) spesso
dimenticate.

Una di queste utility, presente sin dalla versione 2.00 di MS-DOS, e` PRINT,
lo SPOOLer (Simultaneus Peripheral Operation On-Line) che si occupa di stampare
files mentre il nostro PC e` occupato a fare dell'altro; insomma PRINT e`
l'unico barlume di multitasking (standard) nei sistemi MS-DOS (rigorosamente
monotasking per definizione).

Questa capacita` di operare in concorrenza con altre applicazioni, il fatto
che si occupi dell'interfacciamento con la stampante e che "ruba" meno di 7Kb
di RAM ne fa un valido collaboratore per chi sviluppa applicazioni che
prevedono l'uscita su stampante.

A me sembra piuttosto "elegante" un programma che estrae dati da un database
li formatta in un certo modo, li scarica su di un file sequenziale (temporaneo)
e, terminata l'estrazione, passa il file da stampare allo spooler permettendo
di liberare velocemente (come e` noto la stampante e` la periferica piu` lenta
di un computer) la console che si puo` dedicare ad altri compiti.

In questa ottica PRINT ha un difetto: non cancella (a richiesta) un file dopo
averlo stampato; comunque questa piccola pecca puo` essere facilmente aggirata
(per esempio si puo` depositare tutti i files di stampa in una directory il cui
contenuto viene cancellato dall'AUTOEXEC ad ogni reboot del PC).

Per contro la parte TSR di PRINT ha il grosso pregio di rispondere a tutti
quei processi che lo invocano generando l'interrupt $2F e da qui e` nata l'idea
di creare una unit per Turbo Pascal che mi permettesse di comunicare con questo
spooler dai miei programmi TP.
==============================================================================
+-----------+
| Interface |
+-----------+

CONST
~~~~~
MAX_ENTRY_LEN Questa e` la lunghezza delle strighe che vengono passate per
indirizzo attraverso SubmitPacket o direttemente. Vengono
passate in formato ASCIIZ quindi la lunghezza aumenta di un
carattere per accogliere il NUL finale.

MAX_SPOOLER_ENTRY Numero massimo di files in coda, dipende dallo switch /Q:nn
di PRINT (default 10, massimo 32).

MIN_DOS_VERSION Minima versione MS-DOS richiesta:
$0200 (versione 2.00)
oppure
$0300 (versione 3.00)
secondo Peter Norton PRINT e` presente a partire dalla
versione 2.00 ma l'interfaccia dell'interrupt $2F e`
disponibile solo dalla 3.00; mentre per Ray Duncan
l'interfaccia era gia` presente a partire dalla versione 2.00
ma non e` stata documentata fino alla 3.00. Dal momento che
non ho avuto modo di provare sotto MS-DOS 2.xx nel sorgente
(e di conseguenza nella TPU e nel demo) viene richiesta la
versione 3.00 o successiva. Se qualcuno provasse sotto
MS-DOS 2.xx mi piacerebbe avere un feedback.

--+
SPOOLER_INSTALLED |
SPOOLER_NOT_INSTALLED | Valori di ritorno della funzione SpoolerStatus
SPOOLER_CANNOT_BE_INSTALLED | ^^^^^^^^^^^^^
--+

QUEUE_FULL Questo e` l'unico valore (diverso da 0) che ho trovato in
SpoolerResult durante i tests, si verifica quando accodando files
si supera il massimo dichiarato con lo switch /Q:nn. Se qualcuno
ne ottenesse altri mi farebbe cosa gradita se me lo facesse
sapere.

TYPE
~~~~
EntryType e` il tipo stringa che deve essere passato alle funzioni di
accodamento e cancellazione.

QueueType e` il tipo array di EntryType che deve essere passato a SubmitFiles
e ListQueue.

VAR
~~~
SpoolerResult contiene il valore di ritorno delle chiamate alle procedure e
funzioni della UNIT SPOOLER.



+----------------+
| Implementation |
+----------------+

CONST
~~~~~
NUL serve a inizializzare i QueueType passati a SubmitFiles e a ListQueue e
a marcare o testare la fine delle stringhe ASCIIZ.

MAX_ASCIIZ_LEN e` la versione ASCIIZ di MAX_ENTRY_LEN, equivale a
MAX_ENTRY_LEN+1 (espressione che viene accettata dal TP 5.x
ma non dal 4.0).

TYPE
~~~~
ASCIIZType versione ASCIIZ di EntryType.
ASCIIZQueueType versione ASCIIZ di QueueType.

SubmitPacketType parametro per la funzione $0101 (Submit File) di PRINT.

cset parametro per Last.

PathStr (vedi NOTE PER TURBO PASCAL 4.0).

VAR
~~~
regs registri per Intr e MsDos.

HeapFSave variabile puntatore usata per "parcheggiare" il valore di
HeapHerror durante ListQueue.

DosVersion (vedi NOTE PER TURBO PASCAL 4.0).

FUNZIONI e PROCEDURE
~~~~~~~~~~~~~~~~~~~~
InitializeRegisters: in seguito a problemi con SubmitFile (non accodava!!!) ho
introdotto questa procedura che azzera regs prima di ogni
chiamata a Intr o MsDos.

CarryFlag: restituisce true se, al ritorno da una Intr($2F,regs) in carry flag
e` settato (errore).

Str_to_ASCIIZ: trasforma una stringa TP (array di caratteri preceduto da un
byte di lunghezza) in una stringa ASCIIZ (array di caratteri
seguito da un NUL).

ASCIIZ_to_Str: trasforma una stringa ASCIIZ in una stringa TP.

Last: scandisce una stringa partendo dal fondo memorizzandosi (p) e
restituendo la prima posizione di uno dei caratteri del cset c.
(vedi NOTE PER TURBO PASCAL 4.0).

FExpand: (vedi NOTE PER TURBO PASCAL 4.0).

SpoolerStatus: verifica che la versione MS-DOS non sia inferiore a quella
richiesta (se no torna SPOOLER_CANNOT_BE INSTALLED) e che PRINT
sia installato (altrimenti anche SpoolerStatus contiene lo
stesso valore).

SubmitFile: dopo aver verificato che PRINT sia installato (SpoolerStatus)
richiede l'accodamento del file FileString passando l'indirizzo ad
un SubmitPacket con LevelCode=0 (attualmente l'unico valore
possibile) e con l'indirizzo della verisione ASCIIZ di FileString;
se si sono verificati errori SpoolerResult contiene il codice
d'errore.

SubmitFiles: inizializza l'array Queue, ricava il path (dir) da WildCString e
con un ciclo di FindFirst e FindNext richiama SubmitFile; dopo
ogni chiamata se si verifica un errore SpoolerResult contiene il
codice d'errore mentre se l'accodamento ha avuto successo mette il
pathname in Queue.

CancelFIles: dopo aver verificato che PRINT sia installato (SpoolerStatus)
richiede la cancellazione (dalla coda) dei files identificati da
WildCString passando l'indirizzo della versione ASCIIZ di
WildCString; se si sono verificati errori SpoolerResult contiene
il codice d'errore.

CancelAllFIles: dopo aver verificato che PRINT sia installato (SpoolerStatus)
richiede la cancellazione (dalla coda) di tutti i files
accodati; se si sono verificati errori SpoolerResult contiene
il codice d'errore.

HeapFunc: se, in seguito ad una richiesta di allocare memoria (new o getmem),
lo heap manager non riesce ad allocare il blocco di memoria richiesto
chiama una funzione far ($f+), il cui puntatore trova in HeapError,
passandole la dimensione del blocco (dim) e se il valore tornato e` 1
fara` si che la procedura di allocazione torni un puntatore nil.
Il puntatore a questa funzione viene mosso in HeapError da ListQueue.

ListQueue: dopo aver verificato che PRINT sia installato (SpoolerStatus),
inizializza l'array Queue e "parcheggia" il puntatore alla funzione
di errore dello heap contenuto in HeapError e lo sostituisce con
quello a HeapFunc, alloca un array ASCIIZQueueType (ASCIIZ) e
ripristina HeapError, se ASCIIZ non e` stato allocato (nil) esce.
Richiede a PRINT il blocco della coda e la lista dei files in coda
(funzione $0104), verifica il carry falg e nel caso di errore
deposita il codice d'errore in SpoolerResult ed esce; se la funzione
e` giunta buon fine copia dall'indirizzo ottenuto da DS:SI
all'indirizzo puntato da ASCIIZ sizeof(ASCIIZ^) (dimensione
dell'oggetto puntato da ASCIIZ) bytes; quindi sblocca la coda
richiamando la funzione $0105. Trasforma gli elementi di ASCIIZ^ e
li passa a Queue finche' non trova un elemento nullo o raggiunge la
massima dimensione di Queue. Quindi disalloca ASCIIZ^ ed esce.

NOTE PER TURBO PASCAL 4.0
~~~~~~~~~~~~~~~~~~~~~~~~~

Il tipo PathStr, la funzione FExpand e la variabile DosVersion vengono
definiti solo per la versione 4.0 ($IFDEF VER40) perche` gia` presenti nelle
versini 5.x, mentre la funzione Last e` definita per tutte le versioni ma nelle
versioni 5.x poteva essere sostituita da FSplit (divide un pathname nelle su
componenti).

DosVersion: viene caricata nella parte di inizializzazione, tramite la chiamata
alla funzione $30 di MS-DOS, con la versione di MS-DOS.

FExpand: espande il path passato (include il drive e la directory correnti e
converte '.' e '..').
Salva il drive/directory corrente, rende corrente il drive/directory
specificati da path, salva il nuovo drive/directory corrente e
ripristina il drive/directory iniziale.
==============================================================================
Bibliografia:

Ray Duncan, "Advanced MS-DOS programming" 2nd ed., 1988 Microsoft Press
Peter Norton, "PC IBM: guida del programmatore", 1986 Arnoldo Mondadori
("Programmer's guide to IBM PC", 1985 Microsoft Press)
==============================================================================

Questa UNIT (tutti i files SORGENTI, OGGETTO e di DOCUMENTAZIONE) e` di
PUBBLICO DOMINIO.
E` liberamente copiabile e modificabile ma, d'altra parte, non rispondo di
eventuali errori; comunque chi ne rilevasse e` pregato di segnalarmeli cosi`
che possa correggerli.
Se la distribuite ad altri includete tutti i files sopra elencati.
Se la modificate cercate di includere tutti i files sopra elencati piu` la
vostra versione modificata.