SPOOLER

Controls spooler processes.

Syntax

     SPOOLER[DEV=]{ldev

                   devclass

                   devname}

     {;SHOW

      ;OPENQ [;SHOW]

      ;SHUTQ [;SHOW]

      ;START [;OPENQ

              ;SHUTQ][;SHOW]

      ;STOP [;FINISH

             ;NOW]   [;OPENQ

                      ;SHUTQ] [;SHOW]

      ;SUSPEND [ [;FINISH

                  ;NOW] [;NOKEEP

                         ;KEEP]

                 [;OFFSET= [+

                            -] page]

                 [;OPENQ

                  ;SHUTQ] [;SHOW] ]

      ;RESUME [;OFFSET= [+

                         -] page] [;OPENQ

                                   ;SHUTQ] [;SHOW]

      ;RELEASE [;OFFSET= [+

                          -] page][;OPENQ

                                   ;SHUTQ] [;SHOW] }




	CAUTION: When using network printers, avoid using the following commands to suspend the spooler in mid-file: `SPOOLER ...; STOP` `SPOOLER ...; SUSPEND; OFFSET=``anything` `SPOOLER ...; RESUME; OFFSET=``anything` `SPOOLER ...; SUSPEND; NOKEEP` `SPOOLER ...; RELEASE` Many interfaces drop a network connection if the printer is ready to receive data but no data is being sent within a specific time period. The period is configurable at the printer or in the printer's TFTP file (specified in the bootptab entry), but many users simply use the factory default, which is 90 seconds. The timer only runs when the printer is available but the host is not sending data, as is the case during a mid-file suspension. The timer does not run when the printer is unable to print, i.e., it has been taken offline, or places itself offline due to a paper out or toner low condition.

Parameters

ldev

The logical device number of the spooled device.

devclass

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

devname

The device name of the spooled device. The devname parameter 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 spool files 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 to create job or data input spool files 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 the following on the console (or the $STDLIST of an associated user) and terminates.

   Output spooler, LDEV #ldev: Stopped.

You may determine the spooler state at any time by entering the following:

   SPOOLER ldev;SHOW

 

   SPOOLER devclass;SHOW

   SPOOLER devname;SHOW

The STOP option is valid only if a spooler is in the 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.




	NOTE: 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. If the `STOP` is received while the spooler is printing a file, the page number of the last complete page that was printed is saved in the spool file's file label extension (FLABX). The next time that the file is selected for printing by any spooler, the output resumes at the page following the page number saved in the FLABX.

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 the following message on the console (or the $STDLIST of an associated user) and terminates:

   Input spooler, LDEV #ldev: Stopped.

You may determine the spooler state at any time by entering the following:

   SPOOLER ldev;SHOW

The STOP option is valid only if a spooler is in the IDLE or ACTIVE state. Except for a short period during startup when it is in the START state, an input spooler is always in the IDLE or 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 the following on the console (or the $STDLIST of an associated user) and enters the SUSPEND state.

   Output spooler, LDEV #ldev: Suspended.

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 spool file. This is the default.

If you suspend the spooler with the KEEP option and want to force the spooler process to relinquish ownership of its spool file, do this:

   SPOOLER 6;RELEASE

SUSPEND with certain other parameters presents special cases:

SPOOLER dev;SUSPEND;NOW;KEEP with no ;OFFSET=
(NOW and KEEP are defaults.)
With no offset, the spooler suspends as soon as it processes the command. It suspends after processing the current spool file block and reads no more data from the spool file; nor does it flush existing data from the file system or device buffers.
How you resume the spooling affects the subsequent data output.
If you resume spooling by entering SPOOLER dev;RESUME, with no offset, the spooler continues from the point of interruption, and data in the buffer is printed in the normal course of operation. The output appears as though the spooler had never been suspended.
If, instead, you resume spooling by entering
SPOOLER dev;SUSPEND;NOW;KEEP
with an offset, the spooler flushes all buffered data to paper before carrying out the offset request. As a result, you may see more output than you might expect from buffer flushing.
SPOOLER dev ;SUSPEND with any other combination of different options (such as ;NOKEEP or ;OFFSET=).
In such cases, the spooler knows that it will be resuming with a different file or at a different place in the same file. All buffered data is printed to paper before suspending. This may be a fair amount of buffered data.
To avoid generating extra output, enter your offset when you suspend, instead of when you resume. For example:
SPOOLER 16;SUSPEND;OFFSET=1 [vellip] SPOOLER 16;RESUME
Since you specify a page offset, all buffered data is printed to paper before the spooler suspends.
Other considerations:
If a spooler process is suspended in the middle of a spool file and the file is not retained by the spooler, a page number is saved in the spool file's file label extension (FLABX). This page number is either the last complete page that was printed (if no OFFSET was specified) or one page prior to that specified by the final OFFSET applied to the file (with a lower limit of 0). The next time the file is selected for printing by any spooler, output resumes at the page following the page saved in the FLABX.

The SPOOLER dev;SUSPEND command is one example of a command that may interrupt a spooler process while it is printing a file. Other commands that may cause an interruption are:

=SHUTDOWN

 SPOOLER dev;SUSPEND;NOW             (SUSPENDSPOOL)

 SPOOLER dev;STOP;NOW                (STOPSPOOL)

 SPOOLF  nnn;ALTER;DEV=dev            (ALTSPOOLFILE)

 SPOOLF  nnn;ALTER;DEFER             (ALTSPOOLFILE)

 SPOOLF  nnn;DELETE                  (DELETESPOOLFILE)

where dev is device class, the device name, or the logical device number and nnn is the spool file identification number (spoolid) or the set of files to be printed.

Any such command flushes all buffered data to the printer and updates the FLABX before terminating the spooler or releasing the file.

If dev is a device class, it is possible for the SPOOLER command to affect a spooler process that is printing a file and another process that is not. The same is true of the =SHUTDOWN command, which behaves like a SPOOLER...;STOP directed to all spooler processes. The considerations mentioned above apply only to a process that is printing a file when the command is issued. The command takes effect immediately on idle or previously suspended spooler processes.

Similarly, nnn may resolve to one or more spool files, some of which are printing--and some of which are not printing— when the command is issued. The considerations mentioned above apply only to the spool files that are printing. The command takes effect immediately on other spool files.

Beginning with release 2.2, the spooler displays the following for any of the above command situations:

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

This message is intended to reassure the operator that the spooler has accepted the command, since printing may continue for some time while buffered data is flushed.

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 retains a spool file when it is suspended (meaning the KEEP option was specified or taken by default), and the spool file is not subsequently released, the OFFSET option is valid. If no offset is specified with either the earlier SUSPEND or the present RESUME, then output resumes where it left off. If an OFFSET is 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 spool file from the beginning.

RELEASE

The RELEASE parameter directs a suspended output spooler to close (release) a spool file 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.




	NOTE: When the file is released by the spooler, a page number is saved in the spool file's file label extension (FLABX). This page number is either the last complete page that was printed (if no `OFFSET` was specified) or one page prior to that specified by the final `OFFSET` applied to the file (with a lower limit of 0). The next time the file is selected for printing by any spooler, output resumes at the page following the page saved in the FLABX.

FINISH

Directs the spooler to complete the currently active spool file 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.




	NOTE: The `FINISH` option is not valid for spooled input devices.

Either a STOP or SUSPEND that includes the FINISH option may be accelerated to a higher-priority command without waiting for the present spool file to finish printing. For example, SPOOLER...; SUSPEND; FINISH may be followed by:

   SPOOLER...;SUSPEND;NOW

   SPOOLER...;STOP;FINISH

   SPOOLER...;STOP;NOW

Similarly, a SPOOLER...;STOP;FINISH may be accelerated to SPOOLER...;STOP;NOW. To go 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.




	NOTE: The `NOW` option is not valid for spooled input devices.

KEEP

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

KEEP is used as a parameter to the SUSPEND option.
The spooler is actively processing a file or is suspending.
The NOW parameter is also specified or taken by default.

Directs the device to retain ownership of the spool file that it is currently processing. This 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:

NOKEEP is used as a parameter to the SUSPEND option.
The spooler is actively processing a file or is suspending.
The NOW parameter is also specified or taken by default.

Directs the spooler to close the spool file that it is 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 FLABX (file label extension), 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 the page number 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. The page parameter must be an integer representing a physical page offset, either absolute or relative, within the file. Offsets are applied in the order in which 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 page is specified without + or -, then printing resumes at that page, absolute from the beginning of the file. No matter which combination of offsets are specified, the final location is limited by the bounds of the file.

Page Definition

A page is defined as follows:

For CIPER protocol devices: a physical sheet.
For the HP 2680 or HP 2688: a physical sheet (that may contain one or more logical pages).
For serial printers: the OFFSET option (except for OFFSET=1 or OFFSET=0, the beginning of the file) is not reliable. 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 HP 2680 and HP 2688 page printers.

The spooler's serial printer storage manager makes an approximate guess as to the correct page. It is only a guess, however, based on an extremely limited interpretation of the spool file 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 spool file data, looking for escape sequences that 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), SPOOLER notes that this type of page control is in use and assembles its own checkpoint based on the location of this record in the spool file. If a RESUME with OFFSET is later required, it counts 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 records (60) per page. Typically, this is the number of lines that 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, as the following examples show:

For many applications (for example, A4 paper, 8 lines per inch, and so on), 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 that causes paper to advance (say) five lines after printing a line of data. The storage manager counts this as one record.
Control records (those that affect some aspect of printer operation but do not print anything) are included in the 60 record count.

The last two examples come about because the storage manager does not interpret the data in the spool file, as mentioned earlier, and so cannot detect these situations.

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 ldev;RESUME. For the most consistent results with serial printers, you should always include an OFFSET=1 parameter with the SUSPEND option. You can also include the 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(es) associated with the device(s) specified. All other parameters on this command are processed first, so the SHOW option reflects the updated state of the process(es) at the completion of the command executor. Please refer to the note following the example below.

OPENQ

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

OPENQ is the default value for the START option.

SHUTQ

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

SHUTQ is the default value for the STOP option.




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

Operation notes

The SPOOLER command allows you to start, stop, suspend, and resume spooler processes and to 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 spool file. The data may consist of one or more batch jobs, data files, or any combination of the two. Input spool files are private files, meaning that 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 spool files -- files that were created by a user accessing a spooled output device such as a printer or plotter. A spooled output device processes spool files first in order of priority and then by the time the spool file entered the READY state. Only files that have an output priority greater than the outfence are considered for output.




	NOTE: Because this command may 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`.If you use any of the following commands to interrupt printing of a spool file (anywhere but at the end of the file) on a printer that does not support Page Level Recovery (PLR), the spooler displays a warning on your $STDLIST indicating it is initiating a recovery sequence. (Refer to appendix D for details on PLR.) `SPOOLER ...; STOP` `SPOOLER ...; SUSPEND; OFFSET=``anything` `SPOOLER ...; RESUME; OFFSET=``anything` `SPOOLER ...; SUSPEND; NOKEEP` `SPOOLER ...; RELEASE`

Examples

Following are examples of the OFFSET and SHOW options:

A spooler is printing physical page 30 of its output, and the following sequence is entered:
SPOOLER dev;SUSPEND;KEEP;OFFSET=-3 SPOOLER dev;RESUME;OFFSET=-6
Output resumes at page 21 (30-3-6=21).
A spooler is again on page 30 when the following sequence is entered:
SPOOLER dev;SUSPEND;KEEP;OFFSET=-15 SPOOLER dev;RESUME;OFFSET=20
Output resumes at (absolute) page 20.
Under the same original conditions as the previous two examples:
SPOOLER dev;SUSPEND;KEEP;OFFSET=20 SPOOLER dev;RELEASE;OFFSET=-5
The next time this copy is selected by a spooler, its output starts at page 15 (absolute page 20-5).
To ensure that a file resumes at the beginning, enter:
SPOOLER dev;SUSPEND;NOKEEP;OFFSET=1

An example of output using the SHOW option might be:

SPOOLER LP;SHOW



LDEV DEV      SPSTATE   QSTATE   OWNERSHIP      SPOOLID  JOB STEP (*)



 6   LDEV6    IDLE      OPENED   OUT SPOOLER   

14   LDEV14   *SUSPEND  OPENED   OUT SPOOLER    #O237    DATA, WAIT FOR EOD

15   LDEV15   ACTIVE    OPENED   OUT SPOOLER    #O264    CONNECTING

19   LDEV19             OPENED   NO  SPOOLER              





(*)JOB STEP is for network printers only.




	NOTE: If the `SHOW` option is used, the display shows the current state of the selected spooler(s) `at the time that 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. This is because it has not finished acting on the command and updating the process state before the `SHOW` option is performed. If this is so, an asterisk (*) precedes 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.

For network printers, any form of the SPOOLER command which includes the ;SHOW option includes a column labeled JOB STEP. If the spooler is printing a file, the JOB STEP column displays one of the following strings:

   CONNECTING          Trying to open a socket connection

   PRINTING HEADER     Printing the header

   HDR, WAIT FOR EOD   Waiting for the printer to finish the header

   PRINTING DATA       Printing user data

   DATA, WAIT FOR EOD  Waiting for the printer to finish user data

   PRINTING TRAILER    Printing the trailer

   TRLR, WAIT FOR EOD  Waiting for the printer to finish the trailer

   CLOSING CONN        Trying to close the socket connection

   RECOVR BRKN CONN    Trying to reopen a connection lost in midfile




	NOTE: The spooler skips the three `WAIT FOR EOD` job steps for printers which do not support Page Level Recovery (PLR). Such printers support only one-way communication (to the printer), and cannot report that they have finished printing anything. Refer to the "Supported devices" section in chapter 2 for a list of printers which do and do not support PLR.

Use

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

Related information

Commands: SPOOLF, LISTSPF, OPENQ, SHUTQ
Manuals: MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-60115)

SPOOLER

Technical documentation

» Table of Contents

» Glossary

» Index