Skip to main content

Spooler Administration

Spooler Administration

MultiValue spooler administration involves three classes of actions:

  • Using of shell commands such as SETPTR to control the sending of print jobs to the printer.

  • Issuing shell commands to manipulate the jobs, form queues and despool processes.

  • Running the SP-JOBS and SP-STATUS menu driven utilities to manipulate the jobs, form queues, and despool processes.

Form Queue Names And Numbers

Throughout this manual we refer to form queue names and form queue numbers. A form queue is a collection of globals that define and control a pseudo printer. A despool process later comes along and sends the output to a real printer.

A form queue actually has three identifiers:

  • The user-specified form queue name (or form queue number).

  • The system-assigned form queue number.

  • The system-assigned spooler global subscript.

UniVerse-like MultiValue platforms tend to use form queue numbers. Pick-like MultiValue platforms tend to use form queue names. Caché MultiValue supports both. By default, the form queue globals are indexed under form queue number. Each form queue number has a corresponding form queue name.

If the form queue name is numeric, or starts with a letter (other than F, perhaps followed by Q or N, followed by a number), you can use the form queue name, or any of the formats listed below to identify a form queue to one of the SP- commands:

  • A form queue reference in the format nn, for example, 99, describes form queue number 99.

  • A form queue reference in the format Fnn, for example, F99, describes form queue number 99.

  • A form queue reference in the format FQnn or FNnn, for example FN99 or FQ99, describes form queue number 99

  • A form queue reference in the format FQname or FNname, for example FQHP7210 or FNHP7210, describes a form queue named HP7210.

  • Anything else, for example, “STANDARD”, describes the form queue named STANDARD.

In the above rules, the first three result in a reference to a form queue number, and the last two result in a reference to a form queue name. A form queue number will always have a corresponding form queue name, and a form queue name will always have a corresponding form queue number.

In all the administrative commands that ask for a FORM QUEUE you can specify the form queue number or the form queue name. For example, using the commands SP-CREATE and SP-ASSIGN:


means assign print channel 3 to form queue number 12 , with “H” and “S” options.


creates a form queue whose name is HP7210. The form queue number is allocated automatically as the next free unused form queue number.


creates a form queue whose name is F15 and whose form queue number is 15.

SP-FORM F15 HP7210

Referring to the preceding example, this renames the form queue named F15, which is also form queue number 15, to HP7210 and it retains form queue number 15.

Form Queue Groups

you can optionally create one or more form queue groups. A form queue group consists of a list of existing form queues that can be used as a collection of form queues. A form queue group may be used by the despool process to send spooler output to all form queues in the group, rather than just one form queue. form queues that are grouped together should share some commonality, such that grouping them together makes administration easier.

You use SP-CREATE to create a form queue group by specifying GROUP as the second argument, then listing multiple existing form queues. Illegal and duplicate form queue names are ignored. You can create a form queue group without specifying its form queues by specifying the empty string ("") as the third argument, as follows:


You can use the SP-DEVICE command to add, remove, or replace form queues from the form queue group.

MultiValue De-Spool Devices

The MultiValue spooler allows for a despool process to send print jobs from the spooler tables to an external resource, for example a printer. The despool process is controlled using the commands: SP-START, SP-STOP, SP-SUSPEND, SP-RESUME and SP-KILL.

The despool process writes to a device as defined by the form queue. This device is specified when creating a form queue with the SP-CREATE command. You can change the device associated with a form queue using the SP-DEVICE command.

When defining an output device for the despooler, you use a similar syntax as defined for the ObjectScript OPEN statement: Device{:parameters}{:timeout}. You can specify any device supported by Caché and so you can write spooler output to printers, files, tapes, terminal screens, programs, and so on. For further information on devices supported see the Cache I/O Device Guide.

The &HOLD& File

You implicitly create the &HOLD& file the first time you use the SETPTR command and specify mode 3 (the sixth argument). The spooler creates &HOLD& as a directory-type file in the current working directory (identified in the @PATH variable). Normally &HOLD& should be a directory-type file, but it can be pre-created as an anode-type if that is preferred. For example, on a new account, the following commands show this happening:

  Creating &HOLD& file.

  6 lines long.
  0001: F
  0002: &HOLD&
  0003: ^DICT.HOLD
  Bottom at line 6.

In the definition of &HOLD&, attribute 2 means a directory in the Mgr/namespace installation directory will have been created where the file resides. For example, the account NEWACCOUNT, by default this uses namespace NEWACCOUNT and so the &HOLD& file will be a directory called something like C:\InterSystems\Cache\Mgr\NEWACCOUNT\&HOLD&.

This action can be overridden. On a new account, simply create the type of &HOLD& file you want, for example:




If the &HOLD& file has already been created, you can simply delete it with DELETE-FILE and manually re-create it as shown.

The &HOLD& file can therefore be any regular MultiValue file of type DIR (points to an operating system file path), or of type ANODE (a special Caché type suitable for large items). A &HOLD& file cannot be an INODE file.

Form Queue Control

Caché allows for a subroutine to be called either before, or after, or both before and after a job is printed on a form queue. The purpose of the subroutine is to allow an arbitrary sequence of characters to be sent to the spool device, most typically for fine control of the device, such as changing the device from portrait mode to landscape mode.

The general name of the subroutine to be called is contained in the variable, MVCACHEPRINTER. If a subroutine by this name exists, it will be called once at the start and at the end of every print job. If the subroutine named by MVCACHEPRINTER does not exist, no action is taken.


If the print job is printed more than once, for example when copies is set to a value greater than 1, then this subroutine is called multiple times, once per copy of each print job.

Caché also provides for finer control over the routines called by allowing them to be specified separately per form queue via the SP–PREAMBLE and SP–POSTAMBLE commands.

The API of the pre/post–amble routine called is:



  • “AMBLER” is the name of the routine which will handle the queue

  • “OCCASION” is the string “PRE” or “POST” indicating why the routine was called; this allows the same routine to handle both actions

  • “JOBNO” is the job number being output

  • “FQNAME” is the spooler global subscript. To convert this subscript to a form queue name or number, do the following:

      $XECUTE 'SET %EXTERNALNAME = ' : GLOBAL : '("' : FQNAME : '","NAME")'
  • “GLOBAL” is the name of the Caché global holding the spooler data

  • “OUTPUT” is the string of characters that should be sent to the spool device before the job starts (if OCCASION is “PRE”) or after the job finishes (if it is “POST”).

By default, all accounts use the same spooler. Since the preamble and/or postamble subroutine might be called from an account other than where it was defined, the subroutine should be cataloged globally. This is easier to manage than cataloging locally or normally in every account that might need to use it.

Auxiliary Printing

Auxiliary printing occurs when a spool job is directed to a printer connected directly to the terminal or personal computer rather than to that controlled by the spooler. Using this facility, an application can print data to the spooler and the job will appear on the normal spooler tables in the assigned form queue. When the print job is closed, the spool job that was created will be sent to the user’s auxiliary printer.

Auxiliary printing is initiated by the SP-AUX command using the “A” option:


To check if the spool job will be directed to the local printer, look for the “AUX” option on the job in the form queue. For example:


                   FORM QUEUES

Chan Q#   Q name          Width Lines Top Bot P#  Options


0    1    HP7210          132   66    3   3   1    AUX, INFORM

Caché must know the control code sequences to be sent to the terminal to turn on and off auxiliary printing. These are contained in the terminal definition file, TERMDEFS, documented elsewhere. Each terminal type has an entry in the TERMDEFS file. The control definitions used by Caché are “mc5” to turn on auxiliary printing and “mc4” to turn off auxiliary printing. These match those used by most terminal emulators. Without these definitions in the terminal definition file, auxiliary printing will not work.

The SP-AUX command can be used to print existing print jobs to the auxiliary printer. For example, the following command causes Caché to print existing jobs 22 and 23 to the own auxiliary printer:


If your terminal definition does not include codes to turn on and off the printer an error message will be displayed, such as:

Error. No auxiliary printer control sequences available for terminal.

Printer Control Characters

When a print job is sent to a physical printer, a new page is specified by an ASCII 12 character, the form feed control character. A new line is specified by a two-character sequence: an ASCII 13 (carriage return) and an ASCII 10 (line feed). These are the default values. Some printers require other printer control character sequences. For example, a new page may require both a form feed (ASCII 12) and a carriage return (ASCII 13) character. A new line may require just a line feed (ASCII 10) character. If your printer is not formatting correctly, you can use the SP-CONTROL command to change the printer control character defaults.

FeedbackOpens in a new tab