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.