Provided by:
gnuspool_1.7_i386 
NAME
gspl-start - start GNUspool
gspl-start - start a printer
gspl-phalt - halt a printer at end of job
gspl-pstop - halt a printer immediately
gspl-pinter - interrupt printer
gspl-padd - add a printer
gspl-pdel - delete a printer
gspl-pchange - change a printer
gspl-ok - approve alignment
gspl-nok - disapprove alignment
gspl-pstat - test state of printer
gspl-conn - connect GNUspool host
gspl-disconn - disconnect GNUspool host
SYNOPSIS
gspl-start [ jobsize [ printersize ] ]
gspl-start [ -options ] printer [ formtype ]
gspl-phalt [ -options ] printer
gspl-pstop [ -options ] printer
gspl-pinter [ -options ] printer
gspl-padd -options printer formtype
gspl-pdel [ -options ] printer
gspl-pchange -options printer [ formtype ]
gspl-ok [ -options ] printer
gspl-nok [ -options ] printer
gspl-pstat [ -options ] printer state
gspl-conn host
gspl-disconn host
DESCRIPTION
Note that all these programs are in fact hard links to the same
program.
Starting GNUspool
gspl-start without arguments, or with one or two numeric arguments, may
be used to start the GNUspool scheduler, spshed(8), together with
associated programs, such as xtnetserv(8).
The first optional argument specifies to spshed(8) that when allocating
an initial block of shared memory for jobs it should allocate memory
for at least the specified number of jobs.
The second optional argument performs the same function with printers.
These should not strictly be necessary, but on some platforms there are
strange problems about allocating and deallocating blocks of shared
memory whilst a program is running which these are intended to
alleviate.
If spshed(8) is already running, gspl-start will have no effect.
Printers with numeric names in the other form of gspl-start will not
cause confusion if spshed(8) is running.
All other forms of this command will initialise spshed(8), but this is
very strongly not recommended. The scheduler should be started first,
connections to other machines established, possibly using gspl-conn,
and then printers should be started.
Starting printers
gspl-start lj4
will start printer "lj4" if it is halted. It will have no effect if it
is already running. If it is printing, but it has been set to halt at
the end of the current job, then this setting will be turned off, and
the printer will continue at the end of the current job.
gspl-start lj4 a4
will likewise do nothing, other than canceling a "halt at end of
current job" setting, if printer "lj4" is running with the paper type
"a4" (i.e. form type up to the first ""."" or "-" is "a4", ignoring the
"suffix"). Otherwise, printer "lj4" will be halted at the end of the
current job if it is running, gspl-start will wait for it to halt,
change the form type to "a4" and then restart it.
Only "paper types", ignoring the suffix, are compared in deciding
whether the form type is loaded.
Shell-style wild cards (which should probably be protected from
incorrect expansion by shell using quotes) may be used, in conjunction
with the -f option, to start multiple printers, thus:
gspl-start -f 'l*'
gspl-start -f '*[!a-m]'
gspl-start -f 'l*,*[!a-m]'
will respectively start all printers whose names begin with "l", all
printers whose names do not end with "a" through to "m" and both those
classes of printers. Many installations include
gspl-start -f '*'
in the "startup script" to start up all local printers.
Most of the options (e.g. -l and -C) serve only to clarify which
printer or printers are being referred to where there is ambiguity or
the user wishes to restrict the field.
Names of printers starting with digits will not cause any confusion if
spshed(8) is running.
Printers on remote machines may be started by prefixing the machine
name, thus
gspl-start -f host1:l*
Printers are not started on more than one machine at once. You should
start the printers as separate commands:
gspl-start -f '*'
gspl-start -f 'host1:*'
gspl-start -f 'host2:*'
To run gspl-start, the user must have halt and restart printers
permission.
Halting printers
gspl-phalt lj4
will halt printer "lj4" at the end of the current job if it is running
and will otherwise have no effect.
gspl-phalt -f 'l*'
will likewise halt all printers whose names start with "l" etc.
Most of the options (e.g. -l and -C) serve only to clarify which
printer or printers are being referred to where there is ambiguity or
the user wishes to restrict the field.
gspl-pstop is like gspl-phalt, but the printers are halted immediately,
aborting any current job.
Printers on remote machines may be halted by prefixing the machine
name, thus
gspl-pstop -f host1:l*
To run these commands, the user must have halt and restart printers
permission.
Interrupting printers
gspl-pinter lj4
interrupts the given printer (or printers), so as to enable a higher-
priority job to be handled and the interrupted job resumed at the
interrupted page. Note that this will only work as intended if page
delimiters are correctly defined.
Printers on remote machines may be interrupted by prefixing the machine
name, thus
gspl-pinter host1:lj4
To run this, the user must have halt and restart printers permission.
Adding printers
gspl-padd -l tty15 lj4b a4
adds a new printer with the specified parameters. The -l option is
mandatory to denote the device name (or network address) as is the
initial form type, in the above example "a4".
gspl-padd -l 193.112.238.95 -N ptr9 a4
adds a network (terminal server) printer with the IP address given.
Please note that this does nothing to create an initial setup file,
which should be created first.
Printers on remote machines may not be added with this command.
To run gspl-padd, the user must have add and delete printers
permission.
Deleting printers
gspl-pdel lj4b
deletes the specified printer. It is a mistake to try to delete more
than one printer at a time with this command.
Printers on remote machines may not be deleted with this command.
To run gspl-pdel, the user must have add and delete printers
permission.
Changing printers
gspl-pchange with appropriate options and a printer name (with optional
form type) changes the specified parameters of a printer, which should
be halted (and is left halted).
To run gspl-pchange, the user must have add and delete printers
permission.
Alignment pages
If a printer is in "awaiting operator" state, then gspl-ok and gspl-nok
may be used to communicate with it.
If it is in single sheet mode, then the printer will be continued
identically whichever command is used.
If it is waiting for the approval of an alignment page, gspl-ok will
grant approval and continue with printing, gspl-nok will disapprove the
alignment page, causing the alignment routine to be rerun.
To run gspl-ok and gspl-nok, the user must have select printer list
permission.
State testing
gspl-pstat lj4
will return an exit code of 0 (TRUE to shells) if the printer is
running, (i.e. printing or idle) and otherwise 1 (FALSE to shells).
Some other exit code will be returned, together with a message, if
there is an error, e.g. non-existent printer.
To test for specific states, use the state names as listed by
gspl-plist(1), (in fact it takes the state names from the same file
rest.help by default) for example.
if gspl-pstat lj4 error || gspl-pstat lj4 offline
then echo trouble with lj4
fi
Standard state names for gspl-pstat
The following state names are used by gspl-pstat, which are usually
shared with gspl-plist(1) in the message file rest.help by default. As
with other GNUspool programs, the message file may be edited as
required:
offline printer has gone off-line or timed out
error an error has been raised by the printer, driver or GNUspool
halted printer is shut down and printing suspended by GNUspool
startup being initialised to a ready/printing state from the halted
state
idle ready to print next job but nothing to print
shutdown
in process of being taken down to the "halted" state
printing
a job is currently being printed
a/w oper
awaiting operator attention
Connect and disconnect
gspl-conn instructs the GNUspool scheduler to attempt to raise a
connection to the given host, which should be specified in the file
gnuspool.hosts, and not currently active.
gspl-disconn instructs the GNUspool scheduler to close a connection to
the given host, which should be specified in the file gnuspool.hosts,
and currently active.
Both of these commands return immediately; however the connection may
take some time and indeed may not succeed without the command returning
an error message or code.
The user must have stop scheduler permission to run these commands.
OPTIONS
Note that the order of treatment, letters and keywords described below
may be modified by editing the file rest.help - see spsyntax(5).
The environment variable on which options are supplied is the same as
the name of the program invoked except in upper-case and with "-"
changed to "_" (underscore), for example, "GSPL_START". The environment
variable to specify the help file is "SPRESTCONF".
-? or +explain
causes a summary of the other options to be displayed without
taking further action.
-N or +network-device
indicate to that the argument to -l refers to a network device.
-L or +line-device
indicate to that the argument to -l refers to a line (e.g. "tty" or
"lp"-style) device.
-s or +local-only
(for gspl-padd) mark printer as being local only to the host.
-w or +network-wide
(for gspl-padd) mark printer as being available to other machines.
-l device or +device-name device
in the case of gspl-padd, defines the device name or network
address of the printer.
With other options, it may be used to specify which of several
similarly-named printers is intended.
-C nnnn or +classcode nnnn
where nnnn consists of the letters A to P (upper or lower case),
with - to denote ranges, specifies a class code.
in the case of gspl-padd, it defines the class code (subject to
modification by the user's class code) which will be given to the
printer.
With other options, it may be used to specify which of several
similarly-named printers is intended.
-D string or +description string
set the description or comment field associated with the printer to
string.
-v device or +new-device device
for gspl-pchange, reset the device name as specified. Note that the
-l option may help to select the desired printer.
-S or +set-classcode
for gspl-pchange, reset the class code as specified. Note that the
-C option may help to select the desired printer.
-f or +force-all
for gspl-start, gspl-phalt, gspl-pstop, gspl-pinter, gspl-pchange,
gspl-ok, gspl-nok indicate that if the printer name argument
selects more than one printer, then all such printers are intended.
-n or +no-force
cancels the -f option.
-W or +wait-complete
wait for operations to complete before exiting.
-E or +no-wait
do not wait for operations to complete before exiting.
+freeze-current
Save all the current options in a .gnuspool file in the current
directory.
+freeze-home
Save all the current options in a .gnuspool file in the user's home
directory.
FILES
~/.gnuspool configuration file (home directory)
.gnuspool configuration file (current directory)
rest.help message file
ENVIRONMENT
N.B. Separate variables are provided for each program from Release 23
onwards. Previously "GSPL-START" applied to each program.
GSPL_START
space-separated options to override defaults for gspl-start.
GSPL_PHALT
space-separated options to override defaults for gspl-phalt.
GSPL_PADD
space-separated options to override defaults for gspl-padd.
GSPL_PDEL
space-separated options to override defaults for gspl-pdel.
GSPL_PCHANGE
space-separated options to override defaults for gspl-pchange.
GSPL_OK
space-separated options to override defaults for gspl-ok.
GSPL_NOK
space-separated options to override defaults for gspl-nok.
GSPL_PSTAT
space-separated options to override defaults for gspl-pstat.
SPRESTCONF
location of alternative help file.
SEE ALSO
gspl-plist(1), gspl-pq(1), gspl-qlist(1), spsyntax(5),
gnuspool.conf(5), gnuspool.hosts(5), spshed(8), xtnetserv(8).
DIAGNOSTICS
Various diagnostics are read and printed as required from the message
file, by default rest.help.
COPYRIGHT
Copyright (c) 2009 Free Software Foundation, Inc. This is free
software. You may redistribute copies of it under the terms of the GNU
General Public License <http://www.gnu.org/licenses/gpl.html>. There
is NO WARRANTY, to the extent permitted by law.
AUTHOR
John M Collins, Xi Software Ltd.