SPOOLER


SPOOLER

     Controls spooler processes.

SYNTAX

     SPOOLER [DEV=] {ldev    }
{devclass}
{devname }

[ {;START}

{;STOP } [{;FINISH}]
{;NOW }

{;SUSPEND}[ [{;FINISH}]
{;NOW }

[{;KEEP }]
{;NOKEEP}

[{;OFFSET=}[[+/-] <page>] ]

{;RESUME } [;OFFSET= [+/-] <page>]

{;RELEASE} [;OFFSET= [+/-] <page>] ]

[;SHOW]

[{;OPENQ}]
{;SHUTQ}


PARAMETERS


ldev The logical device number of the spooled device.

devclass The device class name of the spooled device.
DEVCLASS must begin with a letter and
consist of eight or fewer alphanumeric characters.

devname The device name of the spooled device.
DEVNAME must begin with a letter and consist
of eight or fewer alphanumeric characters.
Note that it is not possible to have a device
class name and a device name that are the
same. If you enter an alphanumeric character
string, the command searches the device class
list first, and then the device name list.

START

          OUTPUT SPOOLERS:
The START parameter creates and
activates a new spooler process to
own and manage the device and print
spoolfiles destined for it. If a
class is specified, then a spooling
process is created and activated for
each device in the class.

If neither the OPENQ nor the SHUTQ
option is specified, OPENQ is taken
as the default.

INPUT SPOOLERS:
The START parameter creates and
activates a new spooler process to
own and manage the device, to read
data from it and create job or data
input spoolfiles for later processing
by a CI (job) or user process (data).
If a class is specified, then a
spooling process is created and
activated for each device in the class.

STOP

          OUTPUT SPOOLERS:
The STOP parameter terminates the
spooling process associated with the
specified device. If a class is
specified, then spooling processes
for all devices in the specified
class are terminated. A spooler in
the ACTIVE state first moves to the
STOP pending state (shown as *STOP
with the ;SHOW option) while it
finishes its work on its current file
(including any required trailer).
When this is complete, or if the
spooler was previously in the IDLE
state, the spooler displays "Output
spooler, LDEV #: Stopped." on
the console (or the $STDLIST of an
associated user) and terminates. You
may determine the spooler state at
any time by entering SPOOLER ;SHOW.

The STOP option is valid only if a
spooler is in the START, ACTIVE,
SUSPEND or IDLE state, or (if
accelerating a previous STOP ;FINISH
to STOP ;NOW) the STOP pending
(*STOP) state.

If neither the NOW nor the FINISH
option is specified, NOW is taken as
the default.

If neither the OPENQ nor the SHUTQ
option is specified, SHUTQ is taken
as the default.

Because of the large amount of data
buffered in the file system and the
device, an output device may continue
to print, making it appear as if the
STOP parameter has not had any effect
In reality, the spooler stops sending
data to the device when the command
is received but must wait until all
buffered data has been printed before
stopping. Depending on both the
content of the data and the amount of
buffering, this may require a
significant part of a page or even
several pages.

The spooler process notifies you via
the following message that it has
processed the command:

"Output spooler, LDEV#: Received a
command while outputting a file."

INPUT SPOOLERS:
The STOP parameter terminates the
spooling process associated with the
specified device. If a class is
specified, then spooling processes
for all devices in the specified
class are terminated. The spooler
first moves to the STOP pending state
(shown as *STOP with the ;SHOW
option) while it finishes its work on
its current file (closing and
deleting it; rewinding the tape and
placing it offline). When this is
complete, the spooler displays "Input
spooler, LDEV #: Stopped." on
the console (or the $STDLIST of an
ASSOCIATEd user) and terminates. You
may determine the spooler state at
any time by entering SPOOLER ;SHOW.

The STOP option is valid only if a
spooler is in the ACTIVE state.
Except for a short period during
startup when it is in the START
state, an input spooler is always in
the ACTIVE state.

The NOW, FINISH, OPENQ and SHUTQ
options are not applicable to an
input spooler process and result in
an error message if any is used.

SUSPEND

                    The SUSPEND option is valid only for output
spooler processes. It suspends output to one
or more spooled devices. The associated
spooler processes remain alive, but inactive.
A spooler in the ACTIVE state first moves to
the suspend pending state (shown as *SUSPEND
with the ;SHOW option) while it finishes its
work on its current file (including any
required trailer). When this is complete, or
if the spooler was previously in the IDLE
state, the spooler displays "Output spooler,
LDEV #: Suspended." on the console (or
the $STDLIST of an associated user) and
enters the SUSPEND state.

If neither the NOW nor the FINISH option is
specified, NOW is taken as the default.

If neither the KEEP nor the NOKEEP option is
specified, KEEP is taken as the default.

If the OFFSET option is not specified, the
spooler retains the present location in the
output spoolfile. This is the default.

The combination of the NOW, KEEP, and no OFFSET
parameters (all defaults) is a special case. When
the spooler receives this form of the SUSPEND
option, it suspends after processing the current
record. A subsequent SPOOLER...; RESUME with no
OFFSET parameter and without an intervening
SPOOLER...; RELEASE causes the spooler to resume
at the next record, as if it had never been interrupted.

NOTE

Because of the large amount of data buffered in
the file system and the device, the device may
continue to print, making it appear as if the
SUSPEND parameter has not had any effect. In
reality, the spooler stops sending data to the
device when the command is received but must wait
until all buffered data has been printed before
suspending. Depending on both the content of
the data and the amount of buffering, this may
require a significant part of a page or even
several pages.

The spooler process notifies you via the following
message that it has processed the command:

"Output spooler, LDEV#: Received a
command while outputting a file."

RESUME

                    The RESUME option resumes a suspended spooler
process and is therefore valid only for
output spoolers. The spooler must be in the
SUSPEND state. If the spooler retained a
spoolfile when it was suspended (meaning the
KEEP option was specified or taken by
default), and the spoolfile was not
subsequently released, the OFFSET option is
valid. If no offset is specified with either
the earlier SUSPEND or the present RESUME,
then output will resume where where it left
off. If an OFFSET was specified at either
time (or both), the spooler resumes at the
final location indicated by the offsets. If
OFFSET is specified and the spooler does not
have a retained file, a warning is generated
and the spooler prints the next available
spoolfile from the beginning.

RELEASE

                    The RELEASE parameter directs a suspended spooler
to close (release) a spoolfile that it is
currently retaining due to an earlier SUSPEND
;KEEP option. It is invalid and generates a
warning if used in any other context. The
offset option may be used to change the
resumption point of the file the next time it
is selected for printing.

FINISH

                    The FINISH parameter directs the spooler to
complete the currently active spoolfile and
then suspend or stop. This option may be
used only in conjunction with the SUSPEND or
STOP options. If it is used in any other
context, a warning is issued and the FINISH
option is ignored. The FINISH parameter may
not be used with either the KEEP/NOKEEP or
OFFSET parameters.

The FINISH option is not valid for spooled
input devices.

Either a STOP or SUSPEND which includes the
;FINISH option may be accelerated to a higher
priority command without waiting for the
present spoolfile to finish printing. For
example, SPOOLER...; SUSPEND; FINISH may be
followed by SPOOLER...; SUSPEND; NOW,
SPOOLER...;STOP; FINISH, or
SPOOLER...;STOP; NOW. Similarly, a
SPOOLER...;STOP; FINISH may be accelerated
to SPOOLER...;STOP; NOW. Going in the
opposite direction is an error.

NOW

                    Directs the spooler to immediately stop the
current output. This option may be used only
in conjunction with the SUSPEND or STOP
options. If it is used in any other context,
a warning is issued. This is the default.

If NOW is used on the SUSPEND option with
either the NOKEEP or OFFSET parameters, the
spooler prints a trailer if required;
otherwise output pauses and may be resumed
later at the point of suspension.

The NOW option is not valid for spooled input devices.

Either a STOP or SUSPEND which includes the
;FINISH option may be accelerated to a higher
priority command without waiting for the
present spoolfile to finish printing. For
example, SPOOLER...; SUSPEND; FINISH may be
followed by SPOOLER...; SUSPEND; NOW,
SPOOLER...;STOP; FINISH, or
SPOOLER...;STOP; NOW. Similarly, a
SPOOLER...;STOP; FINISH may be accelerated
to SPOOLER...;STOP; NOW. Going in the
opposite direction is an error.

KEEP

                    Valid only if all three of the following
conditions are satisfied:

o Used as a parameter to the SUSPEND option
or is taken as the default.

o The spooler is actively processing a file or
is suspending.

o The NOW parameter is also specified or taken
by default.

Directs the device to retain ownership of the spoolfile
it is currently processing. KEEP is the default.

If the OFFSET parameter is not specified (or this
condition is taken by default), the spooler suspends
after processing the current record.

NOKEEP

                    Valid only if all three of the following conditions
are satisfied.

Used as a parameter to the SUSPEND option.

The spooler is actively processing a file or
is in *SUSPEND.

The NOW parameter is not specified or is
taken by default.

Directs the spooler to close the spoolfile
itis currently processing. The spooler stops
sending data after the current record, ejects
a page, processes any specified OFFSET, saves
the result of that processing (or the last
completely printed page if no OFFSET was
specified) in the spool file's "File LABel
eXtension" (FLABX), prints a trailer with
"(INCOMPLETE)" on it if trailers are enabled,
and returns the file to the READY state. The
next spooler that prints the file starts the
first copy with the page following that saved
in the FLABX, and the file's header and
trailer (if any) include "(RESUMED)" if
printing starts anywhere but at the first page.

[+/-]<page>

                    The <page> parameter may be used only in
conjunction with the ;SUSPEND, ;RESUME, or
;RELEASE option. <page> must be an integer
representing a physical page offset, either
absolute or relative, within the file.
Offsets are applied in the order they are
entered, whether absolute or relative. If
"+" is specified, the offset is adjusted
forward relative to the current location by
the number of pages specified. If "-" is
specified, the adjustment is backward. If
neither "+" or "-" is specified, but a <page>
is specified, then printing resumes at that
page, absolute from the beginning for the
file. No matter which combination of offsets
are specified, the final location is limited
by the bounds of the file.

A page is defined as follows:

For CIPER protocol devices: a physical sheet.

For the HP2680 or HP2688: a physical sheet (which
may contain one or more logical pages).

For all other devices: the ;OFFSET option (except
for OFFSET =1 or OFFSET = 0, the beginning of the
file) is not supported. No error or warning message
is generated if it is used on such devices; however,
results are unpredictable.

This is because page numbers are accurate only for
CIPER protocol devices and HP2680 and HP2688 page printers.

The spooler's serial printer storage manager will
make an approximate guess as to the correct page.
However, it is only a guess based on an extremely
limited interpretation of the spoolfile by the
storage manager, because a serial printer does not
return page data to its storage manager.

The storage manager does not attempt to interpret
the spoolfile data, looking for control sequences
which may advance paper, eject a page, or change
the page length or line density. This would degrade
performance to an unacceptable level. Instead, it
checks the carriage control character supplied as
part of the user's FWRITE intrinsic call.

If that character is an ASCII "1" or an octal 300
(indicating skip to VFC channel 1, which by industry
standard, is a page eject), it notes that this type
of page control is in use and assembles its own
checkpoint based on the location of this record in
the spoolfile. If a RESUME with OFFSET is later
required, it will count these checkpoints to try to
find the proper restarting point. The storage
manager ignores any other carriage control character.

The page eject carriage control is not required in
user data, and many applications do not use it. In
this case, the storage manager is forced to assume a
static number of 60 records per page. Historically,
this is the number of lines which fit on a standard
11-inch page at 6 lines per inch, allowing three
lines of margin at the top and the bottom of the
page. This is often a flawed assumption. For many
applications (for example, A4 paper, 8 lines per
inch, etc.) 60 lines per page is the wrong value.

Other applications are designed for specific forms
and manage their own paper advancement. These
applications may attach a carriage control value to
a record which causes paper to advance (say) five
lines after printing a line of data. The storage
manager counts this as one record.

Control records (those which affect some aspect of
printer operation but do not print anything) are
included in the 60 record count.

In summary, if the storage manager cannot interact
with the device to determine page boundaries, it
uses a carriage control "1" or %300, or 60 records
per page, to simulate checkpoints for SPOOLER
; RESUME. Therefore, for the most consistent
results with serial printers you should always
include an OFFSET=1 parameter with a subsequent
RESUME option, but this does not prevent another
spooler process from printing the file from the
"wrong" place in the meantime.

SHOW

                    The SHOW parameter displays the status of the
spooling process associated with the device(s) or
class(es) specified. All other parameters on this
command will be processed first, so the SHOW option
reflects the updated state of the process(es) at
the completion of the command executor.

OPENQ

                    The OPENQ parameter enables spooling for a
specified logical device, device name, or all
devices of a device class. This allows users
to generate spoolfiles on that device(s).
See the OPENQ command for more information.

SHUTQ

                    The SHUTQ parameter disables spooling for a
specified logical device, device name, or all
devices of a device class. This prevents users from
generating spoolfiles on that device(s). See the
SHUTQ command for more information.

SHUTQ is only valid with the START or STOP
option, and is the default value for the STOP option.

OPERATION

     At least one of the options must be specified for the  SPOOLER
command. SPOOLER DEV=PP is not a valid command; SPOOLER
DEV=PP;SHOW and SPOOLER DEV=PP;OPENQ;SHOW are valid commands.

This command allows the user to start, stop, suspend, and resume
spooler processes, and release files from the spooler process(es).
Spooler processes come in two varieties: input spoolers and output
spoolers.

An input spooler reads data from its device and uses that to create
an input spoolfile. The data may consist of one or more batch
jobs, data files, or any combination of the two. Input spoolfiles
are Private files, meaning they are only accessible to a user
running in privileged mode. They are not printed, but are used
strictly as input for other processes.

An output spooler processes output spoolfiles -- files that were
created by a user accessing a spooled output device such as a
printer or plotter. A spooled output device processes spoolfiles
first in order of priority and then the time the spoolfile entered
the READY state. Only files that have an output priority greater
than the outfence are considered for output.

Because this command may now affect more than one process (if
applied to all devices in a class), it is possible to get errors
for some of those devices and not for others. For example, if class
LP consists of Ldevs 6, 11, and 19, and ldev 11 is already owned by
a spooler process, the command SPOOLER LP; START creates and
activates spooler processes for ldevs 6 and 19, but also generates
the message "DEVICE 11 IS ALREADY SPOOLED".

This command may be issued from a session, job, in BREAK, or from a
program. It is not breakable. It may be executed from the console
or by a user to which the command has been allowed or associated.


EXAMPLE(S)

Here are some examples of the use of the OFFSET option:

A spooler is printing physical page 30 of its output and the following
sequence is entered:

:SPOOLER ; SUSPEND; KEEP; OFFSET = -3
:SPOOLER ; RESUME; OFFSET = -6


Output resumes at page 21 (30 -3 -6).

A spooler is again on page 30 when the following sequence is entered:

:SPOOLER ; SUSPEND; KEEP; OFFSET = -15
:SPOOLER ; RESUME; OFFSET = 20


Output resumes at (absolute) page 20.

Under the same original conditions as the previous two examples:


:SPOOLER ; SUSPEND; KEEP; OFFSET = 20
:SPOOLER ; RESUME; OFFSET = -5


The next time this copy is selected by a spooler, its output will start
at page 15 (absolute page 20 -5).

To ensure that a file resumes at the beginning, enter:

:SPOOLER ; SUSPEND; NOKEEP; OFFSET = 1

A example of output using the SHOW option might be:

:SPOOLER PP;SHOW

LDEV DEV SPSTATE QSTATE OWNERSHIP SPOOLID

14 LDEV14 *SUSPEND OPENED SPOOLED OUT
15 LDEV15 ACTIVE OPENED SPOOLED OUT #O264

NOTE

If the SHOW option is used, the display shows the current state of the
selected spooler(s) at the time the command executor has completed
processing the command. This means that the selected spooler(s) may not
actually be in the requested state, but in a pending state on the way
to achieving the requested state because it has not finished acting on
the command by updating the process state before the SHOW option is
performed. If this is so, an asterisk (*) will precede the process
state on the SHOW display to denote that the state is pending. Please
refer to LDEV 14 in the example display of the SHOW option above.

ADDITIONAL INFORMATION

Commands:   SPOOLF, LISTSPF