NAME

spstart - start GNUspool

spstart - start a printer

sphalt - halt a printer at end of job

spstop - halt a printer immediately

spinter - interrupt printer

spadd - add a printer

spdel - delete a printer

spchange - change a printer

spok - approve alignment

spnok - disapprove alignment

spstat - test state of printer

spconn - connect GNUspool host

spdisconn - disconnect GNUspool host


SYNOPSIS

spstart [ jobsize [ printersize ] ]

spstart [ -options ] printer [ formtype ]

sphalt [ -options ] printer

spstop [ -options ] printer

spinter [ -options ] printer

spadd -options printer formtype

spdel [ -options ] printer

spchange -options printer [ formtype ]

spok [ -options ] printer

spnok [ -options ] printer

spstat [ -options ] printer state

spconn host

spdisconn host


DESCRIPTION

Note that all these programs are in fact hard links to the same program.


Starting GNUspool

spstart 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, spstart will have no effect.

Printers with numeric names in the other form of spstart 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 spconn, and then printers should be started.


Starting printers

        spstart 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.

        spstart 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, spstart 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:

        spstart -f 'l*'
        spstart -f '*[!a-m]'
        spstart -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

        spstart -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

        spstart -f host1:l*

Printers are not started on more than one machine at once. You should start the printers as separate commands:

        spstart -f '*'
        spstart -f 'host1:*'
        spstart -f 'host2:*'

To run spstart, the user must have halt and restart printers permission.


Halting printers

        sphalt lj4

will halt printer lj4 at the end of the current job if it is running and will otherwise have no effect.

        sphalt -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.

spstop is like sphalt, but the printers are halted immediately, aborting any current job.

Printers on remote machines may be halted by prefixing the machine name, thus

        spstop -f host1:l*

To run these commands, the user must have halt and restart printers permission.


Interrupting printers

        spinter 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

        spinter host1:lj4

To run this, the user must have halt and restart printers permission.


Adding printers

        spadd -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.

        spadd -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 spadd, the user must have add and delete printers permission.


Deleting printers

        spdel 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 spdel, the user must have add and delete printers permission.


Changing printers

spchange 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 spchange, the user must have add and delete printers permission.


Alignment pages

If a printer is in ``awaiting operator'' state, then spok and spnok 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, spok will grant approval and continue with printing, spnok will disapprove the alignment page, causing the alignment routine to be rerun.

To run spok and spnok, the user must have select printer list permission.


State testing

        spstat 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 splist(1), (in fact it takes the state names from the same file rest.help by default) for example.

        if spstat lj4 error || spstat lj4 offline
        then    echo trouble with lj4
        fi

Standard state names for spstat

The following state names are used by spstat, which are usually shared with splist(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

spconn instructs the GNUspool scheduler to attempt to raise a connection to the given host, which should be specified in the file /etc/gnuspool.hosts, and not currently active.

spdisconn instructs the GNUspool scheduler to close a connection to the given host, which should be specified in the file /etc/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, for example, SPSTART. 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 spadd) mark printer as being local only to the host.

-w or +network-wide

(for spadd) mark printer as being available to other machines.

-l device or +device-name device

in the case of spadd, 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 spadd, 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 spchange, reset the device name as specified. Note that the -l option may help to select the desired printer.

-S or +set-classcode

for spchange, reset the class code as specified. Note that the -C option may help to select the desired printer.

-f or +force-all

for spstart, sphalt, spstop, spinter, spchange, spok, spnok 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 SPSTART applied to each program.

SPSTART

space-separated options to override defaults for spstart.

SPHALT

space-separated options to override defaults for sphalt.

SPADD

space-separated options to override defaults for spadd.

SPDEL

space-separated options to override defaults for spdel.

SPCHANGE

space-separated options to override defaults for spchange.

SPOK

space-separated options to override defaults for spok.

SPNOK

space-separated options to override defaults for spnok.

SPSTAT

space-separated options to override defaults for spstat.

SPRESTCONF

location of alternative help file.


SEE ALSO

splist(1), spq(1), sqlist(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.


AUTHOR

John M Collins, Xi Software Ltd.