CP/M/CPM_CDROM.iso/mbug/mbug036.arc/UNSPOOL.DOC

Text File | 1979-12-31 | 14KB | 407 lines

       Documentation for UNSPOOL Version 3.2
            for    CP/M 2.0 and up.

AUTHOR:
            Gary P. Novosielski
               Rutherford, NJ
               [phone]
           Evenings and    weekends.

INTRODUCTION:

     UNSPOOL  is  a    program    to send    a standard CP/M    file
such as    a .PRN or .ASM file to the system's  list  or  punch
device,      while     still    allowing  nearly  all  other  system
operations to take place. The  file  is     transferred  during
periods    when console is    waiting    for input.

SYNTAX:

     UNSPOOL [d:]filename.ext [dev]
         or
     UNSPOOL dummy OFF

     [square brackets denote optional parameters]

Where           d:           is  an  optional     drive    spec
                   such as    A:  or    B:.  If     not
                   entered,     the current default
                   drive is    assumed.

           filename.ext    is the name of the CP.M    file
                   to be printed/punched.

           dev           is  the    symbolic name of the
                   output  device  to  be  used.
                   Note   that   the  colon     (:)
                   usually    present     in   device
                   names  is  NOT entered. Valid
                   devices    are  LST  and    PUN,
                   which  refer  to    the physical
                   devices     assigned   to     the
                   logical LST: and    PUN: devices
                   at   the      time     UNSPOOL  is
                   started,    as well     as  PAG,  a
                   special    name  recognized  by
                   unspool.    PAG  refers  to     the
                   same  physical device as    LST,
                   but supplies automatic paging
                   of output by  inserting    Form
                   Feed   characters   into     the
                   output. This  is     useful     for
                   UNSPOOLing    source   files,
                   which  normally    contain      no
                   Form  Feeds.  LST is normally
                   used for    .PRN files, or other
                   types which have     Form  Feeds


Revised    82-01-06          Page 1 of    6







                   already     included.   If     not
                   specified, LST is assumed.

           OFF           If OFF is  specified  instead
                   of   a    device     name,     the
                   operator    will be    offered     the
                   option  of cancelling UNSPOOL
                   if it is    already    running.

           dummy           Because the word    OFF  is     the
                   second  parameter, a filespec
                   is still    needed.    A dummy    name
                   of  "."    will  suffice  as  a
                   place holder.

EXAMPLES:
     UNSPOOL TEST.PRN
         will    send  the  file     TEST.PRN  from     the
current    default    drive to the current LST: device.

     UNSPOOL A:TEST.PRN LST
         is  exactly  equivalent   to    the   above,
assuming  drive    A is the default drive.    Note that the device
name has no trailing colon.

     UNSPOOL B:TEST.ASM PAG
         will send the file TEST.ASM from  drive  B:
to  the     current  LST:    device,    regardless of which drive is
currently the default. Form Feeds will be inserted  whenever
the page length    would exceed 56    lines. If any Form Feeds are
contained  in TEST.ASM,    they will also start a new page. The
program    assumes     that  the  paper  has    been  positioned  to
top-of-form for    the first page by the operator.

     UNSPOOL B:ZINGER.HEX PUN
         will  send  the  file ZINGER.HEX from the B
drive to the current PUN: device. Note that  the  device  is
"PUN" not "PUN:".

     UNSPOOL . OFF
     UNSPOOL *.* OFF
     UNSPOOL OFF OFF
         all  cause an operator    prompt:    "Do you    want
to cancel UNSPOOL?" A single "Y"  or  "N"  (Yes     or  No)  is
accepted from the console as a response. Any other character
is assumed to mean "No".

     UNSPOOL OFF
         causes    the file "OFF.     " to be sent to the
list device.








Revised    82-01-06          Page 2 of    6







OPERATION:

     Upon  loading,     the  program checks to    see that the
the BIOS vector    table pointed to by  the  word    at  location
0001H  is  valid,  i.e.     is  a    table  of  JMP    instructions
containing at least 16 entries.    If an error is detected, the
program    will display an    error message  on  the    console     and
attempt    to warm-boot CP/M.

     If  found, the    BIOS vector table is copied into the
program    segment    which will remain active  during  unspooling
so that    subsequent application programs    running    concurrently
with UNSPOOL will still    have access to the BIOS.

     This  table  is  modified  to trap attempts to    warm
boot the system, perform direct    console     input,     or  perform
direct    disk  sector  writes.  Direct  sector writes are not
permitted (see notes) under UNSPOOL. Warmboot  requests     and
direct console input are handled as described below.

     The  address of the old BIOS vector table, the    BDOS
entry address, and the CCP return address (from    the  top  of
the stack on entry) are    saved in memory.

     The  "dev"  parameter    from  the  command  line  is
checked. If not    valid, an error    message    is typed and control
returns    to the CCP.

     If the    "dev" parameter     is  the  literal  OFF,     the
program     executes  a  BDOS  funcion  0    (System     Reset)     and
terminates.

     The file named    in the command line  is     opened     for
input.    If not present,    the command is echoed to the console
followed by a "?" and control returns to CCP.

     If the    drive is not explicit, the  current  default
drive  number  is  recorded  internally     in case the default
drive is changed while UNSPOOL is active.

     The current  user  number  and     IOBYTE     values     are
checked     and stored internally so that if the user number is
changed, UNSPOOL will still be able to read the    input  file.
If  the    device is changed (using STAT LST:=TTY:    for example)
unspool    will continue to use the physical device  in  effect
at  the     time  the  program  was  initiated. Any application
programs will, however,    use  the  new  values  of  the    user
number and the new physical device assignments.

     If  no     errors     were  detected,  the active program
segment    which monitors all calls to BDOS is  relocated    into
high  memory  just below the CCP. This reduces the available
user program area by 3 K: 4 pages for the UNSPOOL supervisor
segment,  and  8  pages     for  the  CCP    which  is   commonly
overwritten by user program buffers. The BOOT and BDOS jumps
in  low     memory     are modified to protect the CCP and UNSPOOL


Revised    82-01-06          Page 3 of    6







supervisor segment.

     Control is then returned  to  the  console.  Normal
CP/M  operation     will  then  be    possible. Characters will be
sent from the input file to the    output device  whenever     the
console    is idle.

     Whenever an application program or the    CCP requests
console    input using BDOS functions 1 or    10, or a direct    call
into  the  jump     table    at  A(BOOT + 1)    + 6,  the supervisor
segment    intercepts these requests and checks to    see  if     the
console     is  idle. If it is, characters    are transferred    from
the input file    to  the     output     device     until    the  console
becomes     ready,    i.e. a key is actually pressed.    At that    time
the BDOS function or BIOS call    is  executed  normally,     and
control    returns    to the application program.

     If  a    jump  to  BOOT    is  attempted,    this is    also
intercepted by the UNSPOOL supervisor segment.    The  message
"Unspooling in progress" is displayed on the console, and no
actual     boot  takes  place.  Control  is  returned  to     the
protected copy of the CCP instead. Before returning, a    disk
reset  is  performed and the default DMA address is reset to
0080H to simulate a true warm-boot as closely as possible.

     If warmboot is    attempted using    BDOS function 0, the
program    will prompt the    operator with the option to  cancel.
If  the     response  is  "Y", warmboot is    performed using    BDOS
function 0 as requested. Otherwise the request is handled as
with normal warmboot, above.

     If a direct BIOS call to write    a sector to disk  is
attempted,   UNSPOOL   will  display  the  message  "Invalid
operation attempted under  UNSPOOL.  Program  aborted."     The
application  program  will  be    terminated, but    UNSPOOL    will
continue to run. (See Notes.) This restriction applies    only
to direct BIOS writes. All normal file-oriented    (BDOS) reads
and writes are fully supported under UNSPOOL.

     When the input    file is    completely transferred,    or a
1AH  end-of-file  character  is     detected,  the    spool writer
becomes     inactive,  and     passes     on  previously     intercepted
requests  immediately,    without    checking console status. The
sole exception to this is that direct BIOS writes are  still
not  permitted    until  the  next  warmboot.  When  the    next
warm-boot request is detected, the supervisor removes itself
from memory by executing a true    warm-boot, and    informs     the
operator with the message "UNSPOOL completed.".










Revised    82-01-06          Page 4 of    6







NOTES:

     While    UNSPOOL     makes    every  effort to restore the
values of the DMA address, USER    number,    IOBYTE,    and  default
disk  drive  before  returning    control     to  the  program, a
hardware reset may leave these    values    in  an    undetermined
state if unspooling was    actually taking    place at the time.

     When  function     10,  Read  Console  Buffer is used,
UNSPOOL    will transfer characters only until the    first key is
pressed. At that time, no  characters  will  be     transferred
until  the  input  line     is completed by pressing a carriage
return.

     UNSPOOL requires that the List    Status    function  in
the  BIOS  was    properly  implemented at system    installation
time. UNSPOOL will not send characters to  the    LST  or     PAG
devices     unless     it recieves a ready condition from the    List
Status routine.    If the PUN device is used, no  status  check
is  provided  for  by  CP/M, so    a not-ready condition on the
punch may cause    the system to hang up if PUN  was  specified
on  the     command  line.     See the CP/M Alteration Guide for a
discussion of the BIOS List Status routine.

     Although the console is  polled  frequently  during
the  unspooling    of the file, some of the diskette operations
may take a second or two to complete, for example when a new
extent is opened. Since    the console  is     not  polled  during
this  period,  high  speed  typing  may     cause    one  or    more
characters to be lost. This effect will    vary depending    upon
the program being run, the types of input reqests (character
or  line) it uses, and the relative locations on disk of the
spool file and any files in use    by the program.    As a result,
heads-down typing  is  not  reccommended  while     UNSPOOL  is
running.  Some    experience  with UNSPOOL will teach the    user
when caution is    required.

     Although it would be  possible     to  perform  direct
BIOS  writes  while  unspool  is  active,  (indeed  this was
permitted in earlier versions) this action  is    now  trapped
and prohibited.    The reason this    was deemed necessary is    that
some existing software,    for example DU.COM, uses direct    BIOS
writes in a manner which could cause a major system crash if
allowed    under UNSPOOL.

     The  problem  arises  when a program calls the    BIOS
directly (it is    actually calling UNSPOOL's copy    of the    BIOS
table)    to  select  the    drive, set the track and sector, and
perform    direct disk I/O    without     going    through     the  normal
CP/M  file  handling  system.  This causes no problem if the
selecting, addressing, and I/O are all done together, but if
a console input    is done    between    the time the disk address is
set and    the call to read or write a sector, the    disk address
may no longer be valid.    This could cause the  sector  to  be
written     to  the  wrong     disk  address,     or  even  over     the
directory.


Revised    82-01-06          Page 5 of    6








     This is true because a    request    for console input is
taken by UNSPOOL  as  an  opportunity  to  perform  its     own
functions,  which themselves include disk I/O. Although    this
problem    could be eliminated by insuring    that  console  input
is not allowed to intervene between disk addressing and    disk
I/O, it    is not in the author's power to    rewrite    all existing
applications  software.    This better-safe-than-sorry trap was
therefore included.

     Note that direct reads    are NOT    trapped, since    they
do  not     have the same potential for disaster, but still may
be  unreliable    for  the  same    reasons.  It  is   therefore
recommended  that  software using direct disk I/O not be run
under UNSPOOL. Normal CP/M file-oriented  (BDOS)  reads     and
writes    always    re-select  and    re-address  the     disk before
reading    or writing a sector, so    no similar problem exists in
the vast majority of software which  uses  the    normal    CP/M
file handling system.

INSTALLATION:

     The  source  file  is written for assembly with the
MAC assembler. The .HEX    file produced is LOADed     to  a    .COM
file  and executed just    as any normal program. Relocation is
done at    execution time as described above.

     If the    assembly option    EXPAND is set to  TRUE,     tab
characters in the input    file will be expanded to spaces    with
assumed     tab  stops  at     every    eighth    print position.    This
option should be set to    FALSE if the printer driver  or     the
printer    itself can properly handle the tab character. If the
option    PHYSBS    is  set     to TRUE, a backspace character    will
cause the tab expansion     algorithm  to    recognize  backspace
characters  and     decrement the column count when a backspace
is encountered in the input file. This option should be     set
to FALSE if backspace characters are ignored by    the printer.
All  other  control codes except carriage return are assumed
to be non- printing, and are ignored by    the algorithm.

     If tab    expansion is included, the version number in
the signon message will    be followed by "/T".

     The default page size used by the PAG device is set
at 56 in the distribution version. This    value may be changed
by altering the    value  of  the    assembly-time  variable     LPP
(lines per page).

              Gary Novosielski









Revised    82-01-06          Page 6 of    6


-time  variable     LPP
(lines per page).

              Gary Novosielski