SYNOPSIS

gspl-pr [ -options ] [ file ... ]

gspl-rpr [ -options ] [ file ... ]

DESCRIPTION

gspl-pr queues up one or more print jobs for the GNUspool spooler.

gspl-rpr queues up one or more print jobs to a remote queue running the GNUspool spooler. GNUspool does not need to be running on the submitting machine; only the message file and hosts file are required.

If one or more files are specified, each file is treated as a separate spool job, with a title constructed from the file name. If no files are specified gspl-pr and gspl-rpr read from the standard input instead. In this case the job is placed on the queue with a blank title unless otherwise specified.

The standard default options are to print one copy, preceded by a banner page, with the priority, printer and form types specified for the user. The standard banner page will contain: the user name and job title (in large characters), the name of the user who submitted the job (if different), the job number, its size and priority.

Other default options may be set up using environment variables "GSPL_PR" for gspl-pr and "GSPL_RPR" for gspl-rpr and/or .gnuspool files. Any defaults may be overridden by re-specifying that option on the command line.

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_PR" for gspl-pr and "GSPL_RPR" for gspl-rpr and the environment variable to specify the help file is "SPRESTCONF" in both cases.

-? 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, which may possibly be zero.

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.

-C nnnn or +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), the specified class code is reduced to the intersection of (i.e. is "anded" with) the specified class code and the user's own class code.

-d or +delimiter-number

is used in conjunction with the -Dstring option to specify that a page is to be considered complete after reading n delimiter strings. The default value is 1.

-D string or +delimiter string

specifies an alternative delimiter to the default of formfeed as being the end of a page. If a number is given using the -dn option, then the page is considered ended after that number of occurrences of the delimiter.

The string given may contain standard constructs such as

        \n
        \r
        \t

etc to denote linefeed, carriage return etc. Remember that when the job is printed, the printer's setup file may re-specify the delimiter, which will replace the delimiter specified by these options.

-E n or +external-system n

(gspl-pr only) Used internally to signify originating system type. n may be a number, or the name of a system type given in gnuspool.ext. This option may only be used by "root" or "spooler" regardless of other privileges set, as it is intended for use by xtlpd to set parameters on incoming jobs. Any errors in this parameter, including permissions, are silently ignored.

-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, causing the job to be rejected.

-F string or +post-proc-flags string

causes the specified string 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.

-h string or +header string

supplies string as the title for each job, otherwise it is derived from the file name specified. The title appears on the banner page, if this is printed.

-i or +interpolate

causes any file name suffixes .c, .o etc of the files from which jobs are created, to be appended to the form type, unless it already has a suffix, for example:

        gspl-pr -i -f a4 x.c y.ps

would submit jobs using the files x.c and y.ps with form types "a4.c" and "a4.ps" respectively.

-I or +no-interpolate

cancels any previously-specified -i option.

-j n or +job-wait-time n

is relevant only if input to gspl-pr or gspl-rpr is from a pipeline as in

        program|gspl-pr ....

This causes a job to be submitted if no data is received over the pipe for n seconds.

gspl-pr or gspl-rpr will still wait, and may submit any number of subsequent jobs until the pipe is closed by the program generating the output.

Note that nothing can be done by gspl-pr to guess at what output might appear (possibly halfway through a line) if the program writing to the pipe does not flush its output buffer after each occasion that it writes something.

Specify a parameter of zero to cancel any previous -j option, if required.

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

-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 host or +originating-host host

(gspl-pr only) Used internally to signify originating host name, in place of the local host. The host name given should appear in the host file gnuspool.hosts, possibly with the "external" keyword. This option may only be specified by spooler or root users, but is silently ignored in other cases as are all other errors. It is intended for use by xtlpd(8) to set parameters on incoming jobs.

-O flag or +odd-even-flags flag

where flag is one of O, E, A, B or - (the letters may be upper or lower case), cause odd or even-numbered pages to be skipped. or - to reset this flag.

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-pr -c2 -OA ....

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

For this to work properly, page delimiters must be set appropriately.

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

Increasing the priority of a job increases its chances of being printed earlier than it otherwise would be whilst increasing the charge applied to the user in a non-linear fashion.

-P name or +printer name

specifies that the job is to be sent to a printer with the name given, as opposed to printing it on the first available printer with the given form type. name may be a pattern to select any printer matching the pattern.

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

To ``turn off'' a printer name previously specified by a preceding -Pname option, put a single - sign as the printer 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).

-Q hostname or +host hostname

send the job or jobs to the given hostname. Note that hostname must be in gnuspool.hosts on the submitting machine and the submitting machine's hostname must be in gnuspool.hosts on the receiving machine.

If supplied to gspl-pr it will re-invoke gspl-rpr with the same command-line options. It is, however, required for gspl-rpr, which will not try to invoke gspl-pr if it is not supplied (as that could loop endlessly, this could happen if the -Q option was in a .gnuspool file for gspl-pr but not in one for gspl-rpr).

-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, so "-R 3-5" would print pages 3 to 5, "-7" would print pages 1 to 7 inclusive, and "-R 4-" would print page 4 to the end inclusive. "-R 1-" would turn this option off by selecting 1 to the end.

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

-t n or +printed-timeout n

specifies that if retained on the queue (either because of the -q option, or because the setup file has the "retain" keyword as described in the system reference manual on printer setup files), 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.

The user name must exist on the machine to which the job is queued, but this will be ignored if not.

-U user or +originating-user user

(gspl-pr only) Used internally to signify originating user name. This may only be specified by users "spooler" and "root" to have any effect, otherwise the option is silently ignored, as are all errors. It is intended for use by xtlpd(8) to set parameters on incoming jobs.

-v or -V or +toggle-verbose

alternately with successive uses turns on or off the verbose switch. This causes job number information to be output on standard error when job are submitted.

+verbose

turns on the verbose switch. There is no default letter option (however it is possible to create one by editing the message file).

+no-verbose

turns off the verbose switch. There is no default letter option (however it is possible to create one by editing the message file).

-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 previously requested with -m or -w

-z or +no-retain

cancels a request that the job or jobs be retained on the queue after printing.

-Z limit or +job-size-limit limit

limit the size of jobs to limit. limit may be a number, giving a size in bytes, or it may be suffixed with P to indicate a number of pages.

If a job exceeds the limit it is truncated with a warning message, but a job is still created. If the limit is prefixed with an E, then the warning becomes an error, and no job is created.

Supply an argument of a single - to turn off this option.

+freeze-current

Save all the current options in a .gnuspool file in the current directory. This will supply defaults for further gspl-pr or gspl-rpr commands invoked subsequently when started from the directory.

Note that no job will be expected from standard input if no files are specified after including this option.

+freeze-home

Save all the current options in a .gnuspool file in the user's home directory. This will supply defaults for further gspl-pr or gspl-rpr commands invoked subsequently.

Note that no job will be expected from standard input if no files are specified after including this option.

FILES

~/.gnuspool configuration file (home directory)

.gnuspool configuration file (current directory)

rest.help message file

NOTES

N.B. Please note that from release 23 the scheduler spshed(8) is no longer automatically started if it is not running --- use gspl-start(1).

Messages via terminal and e-mail

You can have a message sent to your terminal or receive mail in two circumstances.

1.

When your job has:

a.

Completed normally

b.

Been manually deleted (using gspl-pq(1) etc).

c.

Been automatically deleted after remaining on the queue for a specified time as specified using the -t or -T options.

d.

Been aborted during printing.

2

When your job reaches the top of the queue and:

a.

It has been selected for printing, but operator attention is required for:

i.

Approval of an alignment page

ii.

Confirmation to proceed in single job operation

b.

It has not been selected for printing because no printer is available with the selected form type loaded.

The option -w causes a message to be sent to your terminal, and the option -m causes you to be sent mail in one of the first set of circumstances. If neither is specified, you should still receive mail if a filter process produces output on standard error or terminates abnormally, or if a job is automatically deleted. (Do not forget you can override the "MAILER" program to change this behaviour if required as described in the Reference Manual).

The option -A causes a message to be sent to your terminal, and the option -a causes you to be sent mail in the second set of circumstances.

If any of these are set in the environment and you don't want them, you may suppress them on the gspl-pr command line using -x to turn off both the -w and -m options, and -b to turn off the -A and -a options.

If your terminal cannot be written to, or you have logged out when a message to your terminal is invoked, it will be diverted to the mail program instead.

Queue Timeouts.

When the gspl-pr or gspl-rpr command receives its data on standard input from a pipe, or terminal device, the job is not normally submitted until an end-of-file indication is encountered. This is typically caused by the termination of the process writing to the pipe, or by typing the end-of-file character (often ctrl-D) when input is being taken from a terminal.

In some circumstances the process writing to the pipe may never finish, or the terminal being read from may not be being accessed by a human, but the user may wish to proceed anyway with printing.

The -j option provides a wait timeout in seconds. If some characters have been received, the timeout is set before reading more characters. If the timeout expires before any more characters are read, then a job is created using the characters received so far and gspl-pr or gspl-rpr restarts, possibly making further jobs if more characters arrive.

This cannot be ideal in the case of pipes without some co-operation from the sending process; this is because if stdio (i.e. the C library functions "printf" etc, which is also used by many other languages and applications) then the output is usually ``buffered'' in 1024-byte chunks, and thus up to 1023 bytes of the last part of the output will not be written out to the pipe until the sending process decides to send some more or terminates, and therefore all but the last of the jobs created by use of this option may be ``short'' by up to 1023 bytes.

If the sending process is a 'C' program or other program which the user has access to, then the user should ensure that the routine "fflush" is used after every block of output, thus:

 printf("Totals for......\n";, ....);
 fflush(stdout);

Alternatively, the routine "setbuf" should be invoked to reduce the buffering on standard output.

If the user does not have any access to the sending process this option may have undesirable effects at ``the seams'' of the various jobs due to this buffering. The only successful approach would be to insert a filter process in between gspl-pr and the sending process to ensure that complete pages only were passed through to gspl-pr. It is considered unacceptable to monopolise a printer on speculation that further data may arrive.

A parameter of zero turns off the -j option if it has been set in an environment variable or .gnuspool file.

Delay times.

The -n and -N options provide for the job to be held unprinted on the queue for, or until, a specific time.

The -n option provides a time interval to be held for, in minutes, in hours and minutes, or in hours, minutes and seconds. The following examples all specify the same time interval of 1 hour and 30 minutes. If no colon appears, a time period of minutes is assumed:

 -n 90
 -n 1:30
 -n 1:30:00

The -N option provides an explicit time and possibly a date to be held until. The time may be specified as a 24-hour clock time with optional seconds thus

 -N 16:35
 -N 04:28:32

In these cases the given time in the next 24 hours is taken to be the required time. If a different date is required this can be put in front of the time in the format yy/mm/dd with a comma thus:

 -N 91/2/12,12:30

The year may be omitted, and the date will be taken as a future date. The date will be taken as dd/mm for timezones less than 4 West, otherwise mm/dd.

This allows the printing of long jobs to be printed at a quiet time, overnight for example. Alternatively specifying a delay time can provide an opportunity for thought and possible amendment before continuing.

Environment selection of gspl-pr and gspl-rpr options.

In common with all GNUspool programs, a configuration file mechanism applies to gspl-pr and gspl-rpr.

The environment variable "GSPL_PR" may be used to contain options for gspl-pr and the environment variable "GSPL_RPR" may be used to contain options for gspl-rpr, and the .gnuspool files may contain the keyword "GSPL_PR" or "GSPL_RPR" to select options without having to specify them on the command line.

This enables you to specify, for example, that you always want the -v (job confirmation) option, or that when in certain directories, you always want to use the form type "letterhead", or "invoices", or perhaps 2 copies.

Saving current gspl-pr or gspl-rpr options

The special options "+freeze-current" and "+freeze-home" cause the currently selected set of options to be saved in .gnuspool files in the current directory or home directory respectively. Either or both may be specified.

If no file arguments are given to gspl-pr or gspl-rpr when one or both of these keywords are specified, then the program will not expect to find data on the standard input. If file arguments are given, then the ".gnuspool" file or files are saved before the file arguments are processed. If the ".gnuspool" file cannot be saved, perhaps because the access permission to the current directory is inappropriate, the jobs files specified will still be queued, the program will not fatally abort.

Interaction of gspl-pr and gspl-rpr

If the -Q option is given to gspl-pr, either on the command line or in the environment or .gnuspool files, then gspl-rpr will be invoked with the same command line options (but gspl-rpr will accept its own "GSPL_RPR" environment variable or .gnuspool file options).

Gspl-Rpr, however, will not invoke gspl-pr if the -Q option is not given; this is an error. Remember that the -Q option could be set from a "GSPL_PR" definition in a .gnuspool file, but without a -Q option on an "GSPL_RPR" definition, this would mean that gspl-rpr did not get invoked with a -Q option, so this could give an infinite loop.

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.