Introduction

Normally, output from PRINT statements is directed to the user terminal. However, MultiValue supports mechanisms, such as the (P) option on the PRINT statement, that can be invoked to redirect output elsewhere. This is called SPOOLing. (The Jargon FileOpens in a new tab indicates the acronym stands for a method of decoupling output destined for the printer from the actual device used to print it.)

This document describes the spooler used by Caché MultiValue programs and how to make use of it. The spooler makes use of standard Caché facilities to provide functionality comparable to that found on most MultiValue implementations.

About The Spooler

In Caché, when a user creates the first print job in the global, ^%MV.SPOOL or any other global specified with the SP-GLOBAL command, the runtime automatically initializes and creates the entries necessary to accept spooled data. You can also do this manually with the SP-NEWTAB command.

By default, printed data is collected in the system-wide global, ^%MV.SPOOL. This means that by default there is one spooler table per Caché instantiation, but this can be changed via the SP-GLOBAL command.

Also by default, MultiValue assigns print jobs to the form queue, STANDARD. The SETPTR command is used to manipulate the details of a particular job's output such as its form queue, page dimensions, banner text, and so on. SETPTR can also be used to direct output to a special file called &HOLD&. Output in &HOLD& is not handled by the spooler; administrative action is required before it can be processed.

Note:

Caché MultiValue does not support the option of having an application print directly on a printer. If a MultiValue application really wants to print directly to the device, it must use classes inside the MultiValue application that access the Caché facilities for this purpose.

Caché MultiValue does not support the option of having an application print directly on a printer. Instead, Caché supports the “A” option on the SP-ASSIGN statement. This means the despool process will start to transmit the data from ^MV.SPOOL to the printer while the print job is still being created. This gives a timing effect very similar to direct printing except that the application does not communicate directly with the printer.

Spool Jobs

A spool job can be created in one of three ways:

By using the (P) option on the command line.
By executing a PRINTER ON or PRINT ON nnn statement in MultiValue Basic.
By using the LPTR clause in a CMQL (Caché MultiValue Query Language) statement. For example, LIST VOC LPTR.

In each of these instances, output destined for the printer is collected into a Caché global and grouped together to form a print job. This print job is associated with a form queue. The form queue defines a collection of print jobs destined for a specific printer. Administrators can manipulate the form queue and the individual jobs within it. A despooler process will eventually process the queue, writing information from the Caché global to a specific printer, and clearing the global when all the information has been disposed.

Caché supports the MultiValue concept of a file called &HOLD&. The use of the &HOLD& file is initiated by specifying mode 3 in the SETPTR command, after which all printing output will go to the &HOLD& file instead of the spooler global.

The &HOLD& file is created automatically after the first SETPTR verb is executed that specifies mode 3. Caché MultiValue creates &HOLD& as a directory in your installation hierarchy. The &HOLD& file may be located anywhere; by default, it will be placed in the directory associated with the namespace of the user that creates it. In the example that follows the &HOLD& file points to the C:\TMP directory and so all spooler output in mode 3 will go to operating system files in the C:\TMP folder.

USER:SETPTR 0,132,66,2,2,3,BRIEF
Creating &HOLD& file.
USER:DELETE-FILE &HOLD&
[440] DICT '&HOLD&' Deleted.
[441] Default Data Section '&HOLD&' deleted.
[443] VOC entry for file '&HOLD&' deleted.
USER:CREATE-FILE &HOLD& DIR C:\TMP
[421] DICT for file '&HOLD&' created. Type = INODE
[429] Default Data Section of '&HOLD&' set to use directory 'C:\TMP'.
[437] Added default record '@ID' to 'DICT &HOLD&'.
[417] CreateFile Completed.
USER:DELETE-FILE &HOLD&
[440] DICT '&HOLD&' Deleted.
[441] Default Data Section '&HOLD&' deleted.
[443] VOC entry for file '&HOLD&' deleted.

The &HOLD& file must be of type DIR (an operating system directory/folder) or of type ANODE (a Cache global where each node represents one attribute). For example:

USER:CREATE-FILE &HOLD& ANODE
[421] DICT for file '&HOLD&' created. Type = INODE
[418] Default data section for file '&HOLD&' created. Type = ANODE
[437] Added default record '@ID' to 'DICT &HOLD&'.
[417] CreateFile Completed.
USER:

Child programs that are started automatically inherit the printer status (unless this has been negated by the SP-CONDUCT command). In the following example, the second program “PROG2” will automatically send its output to the spooler even though it never specifically executed a “PRINTER ON” statement. This is because it inherits the printer status from its parent program “PROG1”:

    PROG1
001 PRINTER ON
002 PRINT “Hello”
003 EXECUTE “PROG2”
004 STOP

    PROG2
001 PRINT “World”

In the above example, the child program “PROG2” will inherit the same spooler print job started by its parent program. The resulting spooler print job will have 2 lines consisting of the words, “Hello” and “World”.

Any opened spooler print job will remain open until one of the following occurs:

The program executes the SP-CLOSE command.
The program executes the MVBasic statement: PRINTER CLOSE.
The program that originally started the spooler print job terminates.
The user logs off.
The programs executes a CMQL command such as LIST or SORT. (This might seem an anomaly, but it is UniVerse behavior.)

Note:

The default behavior of spool jobs as described in this section depends on the current emulation. Applications that wish explicit control of spooler behavior should do so with the SP-CONDUCT command.