NAME

       gspl-qchange - change spooled jobs

SYNOPSIS

       gspl-qchange [ -options ] job number ...

DESCRIPTION

       gspl-qchange makes changes to one or more GNUspool spooled jobs, which may be on the local
       host or other hosts on the network. Jobs are specified by the job number, which is
       reported by gspl-qlist(1) in the first column of the default output, or by gspl-pr(1) or
       gspl-rpr(1) when the job is queued with the verbose option. Remote jobs are specified by
       prefixing the job number by the host name and a colon, thus "host:1234". Leading zeroes in
       the job number may be omitted.

       Each of the jobs must be owned by the user, or the user must have permission to edit other
       user's jobs. The user must also have permission to edit remote jobs to operate on remote
       jobs (this is normally set for all users).

       The changes are specified by options, which are as similar as possible to those for
       gspl-pr(1). It is regarded as a mistake not to specify at least one option.

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 "GSPL_QCHANGE" and 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.

       -a or +mail-attention
           requests that a message be sent in the mail to the user if a job is awaiting
           attention, either because it reaches the top of the queue and the required form type
           is currently unavailable or because the form requires alignment.

       -A or +write-attention
           requests that a message be sent to every terminal at which the user is logged in, or
           by mail otherwise if the user is not logged in, if a job is awaiting attention, either
           because it reaches the top of the queue and the required form type is currently
           unavailable or because the form requires alignment.

       -b or +noatt-message
           turns off any job attention messages previously requested.

       -c n or +copies n
           sets the number of copies to be printed to n.

           The maximum number of copies at a time may be restricted to a number for each user
           such as 10. See the output from gspl-user(1) for information on the maximum number of
           copies. If the user has set any priority on queue privilege, this limit is removed.

       -C nnnn or +classcode nnnn
           may be used to set a class code narrow or expand the range of jobs from which jobs are
           selected. It is probably only relevant where the user has override class privilege and
           it is required to expand the default class code to select additional jobs. N.B. This
           does not set the classcode. Use -S to set the classcode.

       -f string or +formtype string
           specifies that the supplied form type (with optional suffix introduced by ""."" or
           ""-"") is used. Note that not all users may be allowed to select form types other some
           pattern, however only the "paper type", i.e. the form type up to the suffix is
           considered when this restriction is active, so the user can still change the form type
           suffix if required. Note that there is no equivalent of the -i (interpolate) option to
           gspl-pr(1).

       -F string or +post-proc-flags string
           changes to the specified string, the data to be passed as the value of the environment
           variable "SPOOLFLAGS" to any program invoked at the time the job is printed. This
           might be as a post-processing filter command, or alternatively some shell command
           invoked as (for example) a "docstart" string.  Please see the GNUspool Reference
           Manual for more details of this.

       -h string or +header string
           replace the title for each job with string. The title appears on the banner page, if
           this is printed.

       -l or +local-only
           in a networked environment requests that the job be printed only on the printers local
           to the machine at which the job is submitted.

       -L or +network-wide
           cancels the request that the job or jobs be printed only on printers local to the
           machine at which the job is submitted.

       -m or +mail-message
           requests a message to be sent in the mail to the user on completion or termination of
           the job.

       -n nn or +delay-for nn
           specifies that the job should be held on the queue for at least nn minutes from the
           current time before being printed. The time may alternatively be specified as hh:mm or
           as hh:mm:ss, specifying a delay in hours and minutes, or hours, minutes and seconds.
           Specify zero to cancel this.

       -N time or +delay-until time
           is an alternative to the -nnn option to specify the earliest time at which the job is
           to be printed. The argument may be hh:mm or hh:mm:ss to give the time of day in
           24-hour clock notation. If the time has passed, then tomorrow is assumed.

           Alternatively a date and a comma may be prefixed to the time in the form mm/dd or
           dd/mm depending upon the local convention for date format used. Thus the resulting
           argument might be

                   10/11,12:30

       -O flag or +odd-even-flags flag
           where flag is one of O, E, A, B or - cause odd or even-numbered pages to be skipped.

           O causes odd-numbered pages not to be printed.

           E causes even-numbered pages not to be printed.

           A and B are useful if more than one copy is to be printed.

           A causes even-numbered pages not to be printed on odd-numbered copies, and odd-
           numbered pages not to be printed on even-numbered copies.

           B is the other way around.

           If you do not understand this, all you have to do is remember that

                   gspl-qchange -c2 -OA ....

           prints all the odd-numbered pages followed by all the even-numbered ones.

       -p n or +priority n
           specifies the priority of the job, between 1 (lowest) and 255 (highest) or some
           narrower range to which the user is limited, unless he or she has the any priority on
           queue privilege.

           A user must have the change priority on queue privilege to invoke this option.

       -P name or +printer name
           specify name as the destination printer for the job. name may be a pattern to select
           any printer matching the pattern, or - to cancel the selection and make it the first
           available printer.

           A user may be limited to a range of printers which must be a superset of name.

       -q or +retain
           requests that the job or jobs be retained on the queue with copies set to zero after
           printing, for explicit deletion, or automatically at the expiry of the timeout (as set
           by the -tn option).

       -r or +banner
           restores banner pages previously suppressed using -s.

           Note that some form types may be set up never to use banners regardless of this
           option.

       -R m-nor +page-range m-n
           specifies that pages m through to n inclusive are to be printed. This does of course
           assume that the job has recognisable pages. If m or n are omitted, then "the
           beginning" or "the end" respectively is assumed.

       -s or +no-banner
           suppresses any banner page (large letter user name etc) which is printed before the
           job itself.

           Note that some form types may be set up always to print banners regardless of this
           option.

       -S nnnn or +set-classcode nnnn
           where nnnn is some collection of the letters A through to P inclusive (upper or lower
           case) with - to indicate ranges, requests that the job be given the specified class
           code.

           The class code of a job may restrict which printers the job may be printed on, or
           which other users can display details of the job.

           In normal circumstances (except where the user has override class privilege as
           displayed by gspl-user(1)), the specified class code is reduced to the intersection of
           (i.e. anded with) the specified class code and the user's own class code.

       -t n or +printed-timeout n
           specifies that if retained on the queue the job will be deleted automatically after n
           hours. The default value is 24 hours, and the maximum value is 32767 hours (nearly 4
           years).

       -T n or +not-printed-timeout n
           specifies that if held on the queue without being printed, the job will be deleted
           automatically after n hours. The default value is 168 hours (1 week), and the maximum
           value is 32767 hours (nearly 4 years).

       -u name or +post-user name
           requests that the specified user name be substituted for the submitting user on the
           banner page optionally printed at the start of the job. The job still remains the
           responsibility of the submitting user.

           To "turn off" a user name specified in a previous -uname option, put a single - sign
           as the user name.

       -w or +write-message
           requests a message to be sent to every terminal at which the user is logged in, or by
           mail otherwise if the user is not logged in, when the job is completed or terminated.

       -x or +no-message
           turns off any job completion messages (-m or -w previously requested.

       -z or +no-retain
           cancels a request that the job or jobs be retained on the queue after printing.

       +freeze-current
           Save all the current options in a .gnuspool file in the current directory. If there
           are no jobs given to operate on and this is specified, then gspl-qchange will quit
           without error. If it is unable to save the options and jobs are specified, then gspl-
           qchange will continue.

       +freeze-home
           Save all the current options in a .gnuspool file in the user's home directory. If
           there are no jobs given to operate on and this is specified, then gspl-qchange will
           quit without error. If it is unable to save the options and jobs are specified, then
           gspl-qchange will continue.

FILES

       ~/.gnuspool configuration file (home directory)

        .gnuspool configuration file (current directory)

       rest.help message file

ENVIRONMENT

       GSPL_QCHANGE
           space-separated options to override defaults.

       SPRESTCONF
           location of alternative help file.

SEE ALSO

       gspl-rpr(1), gspl-pr(1), gspl-pq(1), gspl-qdel(1), gspl-qlist(1), spsyntax(5),
       gnuspool.conf(5), gnuspool.hosts(5).

DIAGNOSTICS

       Various diagnostics are read and printed as required from the message file, by default
       rest.help.

NOTES

       The -C option selects the class code for finding the jobs; if you have override class
       privilege, but your default class code does not allow the jobs "to be seen" in the output
       of gspl-qlist(1), then you may need to specify this. The -S option sets a new classcode,
       which may be anded with your default class if you do not have override class privilege.

       Any errors are reported with appropriate messages on standard error. If any errors are
       detected operating on several jobs, the exit code will correspond to the last such error
       displayed.

EXAMPLES

       To change the number of copies of job 24139 to 3

               gspl-qchange -c3 14139

       To changed the formtype to a4.ps for 3 jobs including one on a remote machine, "avon"

               gspl-qchange -f a4.ps 24139 26921 avon:21941

       Changing all the jobs associated with printer "laser" to come out on printer "ljet" may be
       done with a shell script like this:

               gspl-qlist -F "%N %P" | grep laser | while read JOB REST
               do
                       gspl-qchange -P ljet $JOB
               done

       Or you can do it in one operation with this "one-liner":

               gspl-qchange -Pljet `gspl-qlist -F"%N %P"|grep laser|sed 's/\(.*\) .*/\1/'`

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.