The Caché MultiValue Spooler
Spooler Commands
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

The list of supported commands have been mainly derived from the Pick/jBase/Reality platforms but can appear to some extent on other platforms. The following is a summary of the commands available from the command line (and also embedded into applications).

Most (but not all) of the commands take the format
USER:SP-XXXXXX [ ARG1  [ ARG2 ... ]]
and if the arguments are not entered on the command line, they will be prompted for. The following example shows an invocation of SP-DEVICE with all the arguments being specified on the command line:
USER:SP-DEVICE STANDARD "|PRN|HPLJ80"
The following example shows two invocations of SP-DEVICE issuing prompts for unspecified arguments:
USER:SP-DEVICE
 
FORM-QUEUE   DEVICE: STANDARD    HPLJ80
USER:SP-DEVICE
 
FORM-QUEUE   DEVICE: STANDARD
 
DEVICE: HPLJ80
USER:
The available spooler commands and their implementation status follow.
SETPTR
The SETPTR command lists and sets the current printer settings.
SETPTR [chan,width,depth,topmargin,botmargin,mode,option[,option]]
SETPTR with no arguments lists the current printer settings.
To change one or more printer settings, specify the desired positional argument(s) with the appropriate leading commas.
Positional Argument Description
chan The affected print channel (unit number). The default is 0.
width Page width in characters. The default is 132. You can also use TERM to change width.
depth Page depth in lines (number of lines per page). The default is 66. Setting depth to 0 disables pagination. You can also use TERM to change depth.
topmargin Size of top of page margin, in lines. The default is 3.
botmargin Size of bottom of page margin, in lines. The default is 3.
mode
Printing mode:
1 directs output to the spooler where it can later be manipulated (The default).
3 sends the output to the &HOLD& file.
option
One or more of the following in any order. Multiple option values must be separated by commas.
AT [FORM QUEUE] – when using print mode 1, sends the output to the specified form queue.
AUX – turns on auxiliary printing and hence all print jobs will not go to the spooler or the &HOLD& file, but will instead be sent to the auxiliary printer attached to the user’s terminal.
BANNER [text] – In print mode 1, it specifies the text to be printed on a one-page “banner” preceding the job output. In print mode 3, it sets the item ID in &HOLD&: BANNER name. The text is a quoted string, enclosed with either single quotes or double quotes. This string may include commas and multiple blank spaces.
BANNER NEXT [text] – For print mode 3, it designates that the item id of the entry in the &HOLD& file be incremental; that is, each successive print job creates a new entry in the &HOLD& file. The optional [text] specifies the text to be printed on a one-page “banner” preceding the job output.
BANNER UNIQUE [text] – For print mode 3, it designates that the item id of the entry in the &HOLD& file be constant; that is, successive print jobs will overwrite the previous entry because they all have the same item id in the &HOLD& file. The optional [text] specifies the text to be printed on a one-page “banner” preceding the job output.
BRIEF – specifies that changes to the current printer settings are implemented without confirmation prompts.
COPIES [n] – sets the number of times the job will be printed (applicable only for print mode 1).
EJECT [[m-]n] – EJECT specifies that the spooler should add one formfeed at the end of each print job. EJECT n specifies that the spooler should add n formfeeds at the end of each print job. EJECT m-n specifies that the spooler should add n formfeeds at the end of each print job, and m formfeeds at the beginning of each print job.
FHEADN – synonym for HEADON.
HEADN – synonym for HEADON.
HEADON – prints banner output at the start of a print job. The opposite of NOHEAD.
HOLD – indicates the job should be held in the queue after printing.
INFORM – indicates that the print number of the job should be sent to the user terminal when the job is created.
KEEP – the print job is kept open until the user exits the MultiValue Shell, a subsequent SETPTR command is executed for this job, or the job is closed via the SP-CLOSE command.
NFMT – synonym for NOFMT.
NHEAD – synonym for NOHEAD.
NOEJECT – specifies that no formfeeds are to be issued at the end of a print job.
NOFMT– suppresses all formatting for a print job, including pagination and top and bottom margins. To set this option for all print channels for the account, use SP-CONDUCT bit 128.
NOHEAD – suppresses banner output at the start of a print job. This is the Caché default. The opposite of HEADON.
NOINFORM – indicates that the print number of the job should not be sent to the user terminal when the job is created.
OPEN – This is the same as the KEEP option.
SKIP – the job output should be skipped, that is, not sent to any physical device.
UNPROTECT – cancels any security controls for the job (useful only for print mode 1; once set it cannot be unset).
DEFAULT (or DFLT) — causes all unspecified positional arguments to revert to the initial systemwide default values, regardless of emulation.
NODEFAULT (or NODFLT) — causes all unspecified positional arguments to retain their current values, regardless of emulation.
After specifying these settings, SETPTR prompts you to confirm them with a Y or N, unless you specified the BRIEF option. If you specify an invalid option, SETPTR informs you with a Warning, then sets all of the valid specified arguments.
In Caché MultiValue, unspecified values for width, depth, topmargin, botmargin, or mode default to the systemwide defaults. This behavior for unspecified values is emulation-dependent. For example, SETPTR 0,,,,,3 reverts these four settings to the defaults in Caché MultiValue. In other MultiValue emulations, these four settings retain their previously set values. This behavior can be overridden for any emulation by specifying the DEFAULT or NODEFAULT option keyword.
If the &HOLD& file does not exist, SETPTR with mode=3 creates &HOLD& as a directory-type file in the current working directory (identified in the @PATH variable). For example, Mgr/namespace. Normally &HOLD& should be a directory-type file, but you can pre-created it as an anode-type file if that is preferred. To do this, you can use CREATE-FILE &HOLD& ANODE to create &HOLD& as a MultiValue global. In this case, a subsequent SETPTR with mode=3 writes to this existing &HOLD& ANODE global file. You must specify ANODE; by default CREATE-FILE creates an INODE file. An INODE file cannot be used by SETPTR.
BRIEF means that changes to the current printer settings will be made without displaying the changes and prompting you to confirm them. Thus, SETPTR ,,64 prompts you for confirmation before it sets the page width to 64 lines; SETPTR ,,64,,,,BRIEF sets the page width to 64 lines without prompting for confirmation.
You can establish the SETPTR settings for print channel 0 as the systemwide default settings for print channel 0 by issuing the SETPTR.DEFAULT command.
SETPTR.DEFAULT
SETPTR.DEFAULT [ (D) ]
The SETPTR.DEFAULT command takes the current print channel 0 settings and establishes them as the print channel 0 default settings. SETPTR.DEFAULT must be run from the SYSPROG account. Before issuing SETPTR.DEFAULT you define the print channel 0 settings using SETPTR. SETPTR.DEFAULT makes these settings the print channel 0 defaults for all future SETPTR commands systemwide. SETPTR.DEFAULT has no effect on print channels other than print channel 0. These SETPTR.DEFAULT settings remain in effect across system reboots until you issue a SETPTR.DEFAULT (D) command. The (D) option reverts all settings to the initial printer default settings.
SP-ASSIGN
SP-ASSIGN ? 
SP-ASSIGN {formspecs} {options}
This command assigns a printer form queue and printer options to a printer channel. It can also be used to clear existing printer channel assignments. SP-ASSIGN is one of the commands that does not fit the usual command format.
The ? argument displays the current spooler options.
The formspecs argument specifies the assignment (or deassignment) of a form queue. This form queue is created using SP-CREATE. In Caché MultiValue, and several MultiValue emulations, the specified form queue must already exist. In D3, MVBase, R83, POWER95, and Ultimate emulations, SP-ASSIGN automatically creates the named form queue if it doesn’t exist, and then assigns it. This behavior can be changed using SP-CONDUCT bit position 8192.
The formspecs are as follows. Where specified, the leading equal sign is mandatory; a space after the equal sign is optional:
In D3 and related emulations, you can use SP-ASSIGN to create a new form queue with a user-chosen number. For example, SP-ASSIGN F3 will create a queue numbered 3 and named F3 if queue #3 doesn't already exist. If you do that, you still need to either use SP-DEVICE to set the queue's despooler, or use other commands to move jobs from the queue to other queues for printing.
You can specify one or more options values in any order (for example, (AMU). The following options values are supported:
For example,
USER:SP-ASSIGN =MYFORMQUEUE 2 (HS
assigns print channel 0 to the form queue MYFORMQUEUE, with 2 copies printed per print job. The print job will be held (H) and printing suppressed (S).
Assigning options values deletes any prior options values. The M option is initially provided by default. When M is not specified, the form queue informs by default.
To view the options you have assigned, use SP.LOOK or SP.ASSIGN ?. These two commands display other additional information and display the copies and options values in different formats.
SP-AUX
SP-AUX JobNumber[-JobNumber] [JobNumber[-JobNumber]] [(S)]…
This command takes a number of print jobs and sends them to the auxiliary printer attached to a user terminal. The terminal must have the codes defined to control an auxiliary printer. Assuming these codes exist, the SP-AUX command turns on auxiliary printing attached to the terminal, transmits the specified jobs, and then turns off the auxiliary printer.
The jobs to be transmitted can be any number of jobs, a range of jobs such as 25-28, or any combination (97 100 104-109).
The (S) option is the “silent” option. When this is set, notification will be sent to the terminal that auxiliary jobs are being printed.
SP-CLEAR
SP-CLEAR [form-queue]
This command clears all the jobs from the specified form queue.
SP-CLOSE
SP-CLOSE {(Rnnn} 
SP-CLOSE closes print jobs that are currently open due to the KEEP option specified in SETPTR. Without a job number, this command will close ALL print jobs that are currently open for the current user. The use of the (Rnnn) option means only print job nnn will be closed.
SP-CONDUCT
SP-CONDUCT [(V)]
SP-CONDUCT ?
SP-CONDUCT nnn [nnn [...]] [(V)]
The SP-CONDUCT command allows you to control the conduct of the spooler to accurately reflect your own application’s needs. SP-CONDUCT settings will override default settings established for the current emulation. Users who wish this to happen in every session should add SP-CONDUCT to the login command.
SP-CONDUCT has three syntactical forms:
The following are the available bit positions and their symbolic names:
Bit Position Symbolic Name Description
1 CLOSE_CMQL Any CMQL command that terminates will automatically close any opened printer spooler job (unless SP-OPEN is in effect).
2 CLOSE_INTERNAL Same action as 1, except it applies to Caché emulation commands such as WHO or WHERE.
4 CLOSE_PROC Same action as 1, except it applies to PROCs and PARAGRAPHs.
8 CLOSE_PROGRAM Same action as 1, except it applies to user-written applications written in MVBasic and CATALOGed.
16 UNIQUE_JOB All new programs will automatically get their own printer spool job and will close that printer spool job upon termination (unless SP-OPEN is in effect).
32 NO_INHERIT New programs will NOT inherit the printer flag from their parent program.
64 UNIQUE_CMQL Each MultiValue query will have a unique print spooler job.
128 PAGINATE Default Pagination. Spooler print jobs will have pagination set by default. That is, by default a print job issues a form feed every 66 lines and adds a 3 line top margin and a 3 line bottom margin. This is the default for Caché, and for UniVerse and UniData emulations. Pagination is not the default for other emulations; to paginate a print job, they must specify a HEADING or FOOTING.
256 HEADING_FIRST_IMMEDIATE If set, the first HEADING statement will be executed immediately. Otherwise, HEADING is not executed until the application comes to a new page.
512 HEADING_SUBSEQUENT_IMMEDIATE Same as 256, except second and subsequent HEADING statements are executed immediately.
1024 PAGE_LAST_LINE A HEADING statement is executed when the application writes to the last line of the old page. Otherwise, HEADING is executed when the application writes to the first line of the new page. This setting is ignored by CMQL.
2048 NO_INITIAL_FF If this is set and HEADING is the first output of the spooler job, a leading form feed (FF) is not issued. Otherwise, the first HEADING executed issues a leading form feed.
4096 CLOSE_ALL If set, a PRINTER CLOSE with no argument closes all print channels. If not set, a PRINTER CLOSE with no argument closes only print channel 0.
8192 CREATE_FQ Automatically create a form queue. If SP-ASSIGN is used to assign to a form queue, and the form queue does not exist, this bit determines the behavior. If set, SP-ASSIGNautomatically creates the form queue. If this bit is not set, an error message is displayed and the SP-ASSIGN fails.
16384 FF_INHIBIT Inhibits the form feed inside a heading when the heading is generated with the MVBasic EXECUTE statement with either a CAPTURING or an OUTPUT clause.
32768 SP_DEFAULT Assigns default page size. Specifies the behavior if you use SP-ASSIGN to assign a printer to print channel 0 and no page size has been assigned for that form queue. If set, the printer page size defaults to the system default. If not set, the printer page size defaults to the most recent setting for print channel 0. See SP-PAGESIZE.
65536 SHARE_HEADING  
These bit position values are additive. The default setting for each emulation is:
Emulation Value
Cache 129 (1 + 128)
D3 95535 (1 + 2 + 4 + 8 + 32 + 256 + 1024 + 4096 + 8192 + 16384 + 65536)
IN2 15 (1 + 2 + 4 + 8)
Information 15 (1 + 2 + 4 + 8)
jBase 38704 (16 + 32 + 256 + 512 + 1024 + 4096 + 32768)
MVBase 96047 (1 + 2 + 4 + 8 + 32 + 256 + 512 + 1024 + 4096 + 8192 + 16384 + 65536)
PIOpen 15 (1 + 2 + 4 + 8)
Pick 5903 (1 + 2 + 4 + 8 + 256 + 512 + 1024 + 4096)
Prime 15 (1 + 2 + 4 + 8)
Reality 104224 (32 + 256 + 512 + 1024 + 4096 + 32768 + 65536)
R83 96047 (1 + 2 + 4 + 8 + 32 + 256 + 512 + 1024 + 4096 + 8192 + 16384 + 65536)
POWER95 96047 (1 + 2 + 4 + 8 + 32 + 256 + 512 + 1024 + 4096 + 8192 + 16384 + 65536)
UDPICK 192 (64 + 128)
Ultimate 96047 (1 + 2 + 4 + 8 + 32 + 256 + 512 + 1024 + 4096 + 8192 + 16384 + 65536)
UniData 192 (64 + 128)
Universe 129 (1 + 128)
SP-CONTROL
SP-CONTROL form-queue [ff,nl[,lff]]
This command is used to define what control characters are used by the despool process when outputting a print job to a printer. By default, a new page is defined by an ASCII 12 form feed character, and a new line is defined by a two-character sequence: an ASCII 13 (carriage return) and an ASCII 10 (line feed). These defaults are not appropriate for all printers. A new page on some printers requires both a form feed and a carriage return character (ASCII 12 and 13). A new line on some printers requires just a line feed character (ASCII 10).
Define the new page sequence using the ff parameter. Define the new line sequence using the nl parameter. The available values are: LF = line feed (ASCII 10); FF = form feed (ASCII 12); CR = carriage return (ASCII 13); nnn = a single character, specified by the corresponding ASCII decimal integer value. You can specify multiple characters by using the underscore symbol, for example, CR_LF.
To leave the existing value unchanged, omit the parameter, leaving the placeholder comma when necessary. For example, SP-CONTROL HP7210 ,CR_LF. To revert a value to the system default, use the value DE. For example, SP-CONTROL HP7210 DE,DE.
On UNIX® platforms, SP-CONTROL converts a CR+LF sequence into a LF sequence. This is intended to aid developers programming applications that write to both Windows systems and UNIX systems: Windows systems require a CR+LF sequence for a new line and UNIX systems require simply a LF sequence. Therefore, if you use a CR+LF sequence in a SP-CONTROL command for a form queue that outputs to a UNIX file, Caché converts this sequence to LF only.
The optional lff parameter specifies the form feed sequence for any leading form feeds at the start of a line. If lff is defined, the ff parameter is ignored, and only form feeds at the start of a line are translated. A form feed found in the middle of a line is not translated. This parameter is used to support binary data in a print job. Once lff is set, you can print binary data as follows:
PRINT CHAR(255):"BINARY":
PRINT binarydata
PRINT "Hello World"
This program translates the form feed in the first line. The binarydata value is then output without translation. This is followed by the “Hello World” character string without any intervening new line sequences.
SP-COPY
Copies one or more spooler jobs. There are two syntactical forms: the first copies a spooler job to another spooler job; the second copies a spooler job to a MultiValue file defined in the VOC.
SP-COPY jn1 {jn2 {jn3 ...}} {(DOV)} TO: {jna {jnb {jnc ...}}}
With this command format, one or more spooler jobs (jn_) are copied to new spooler jobs on the spooler. Multiple job numbers are separated by spaces. If an alternate job number is specified in the TO: prompt, then it is copied to this print job number. If no alternate job number is specified, the next available job number is automatically used.
SP-COPY jn1 {jn2 {jn3 ...}} {(DOV)} TO: ({DICT} fna) {itemidA {itemidB ...}}
This form of the command, where the output file name is given by (fn_) or (DICT fn_), the jobs are copied to the MultiValue file. If an alternate item id is specified in the TO: prompt, then the job is copied to this item id. If no alternate item id is specified, the output item id becomes the job number. The MultiValue file can be either a Caché global or a directory as defined by your computer's file system. Note that a Caché global (INODE file) has a maximum size limit of roughly 3.5 million characters; output beyond that limit is truncated and warning message is issued. To copy spooler jobs larger than that, you can use CREATE-FILE to create a target file of type ANODE; however, an ANODE file larger than 3.5 million characters encounters the same maximum size limit when being accessed or edited.
The optional DOV letter codes perform the following operations: the (D) option deletes the original job once the copy has completed successfully. The (O) option overwrites any existing target output; without this option, if the target already exists an error is reported. The (V) option reports in Verbose mode, giving additional information about what is copied and what is deleted.
The following example copies spooler job number 4 and 5 to other spooler jobs. Because no target job numbers are supplied, they are automatically allocated:
USER:SP-COPY 4 5
TO:
Job 4 copied to job 21
Job 5 copied to job 22
USER:
The following example copies spooler jobs numbered 4 and 5 to specified spooler jobs numbered 1001 and 1011. The D option means that once the copy executes successfully, jobs 4 and 5 are deleted:
USER:SP-COPY 4 5 (DV
TO:1001 1011
Job 4 copied to job 1001
Job number 4 deleted.
Job 5 copied to job 1011
Job number 5 deleted.
USER:
The following example copies spooler jobs numbered 4 and 5 to the Windows directory C:\TMP. Because the program specifies no item ids, the file names default to the job numbers:
USER:CREATE-FILE C_TMP DIR C:\TMP
[421] DICT for file 'C_TMP' created. Type = INODE
[429] Default Data Section of 'C_TMP' set to use directory 'C:\TMP'
[437] Added default record '@ID' to 'DICT C_TMP'.
[417] CreateFile Completed. 
USER:SP.COPY 4 5 (VO
TO:(C_TMP
Job 4 copied to OS file C:\TMP/4 
Job 5 copied to OS file C:\TMP/5
USER:
SP-COPIES
SP-COPIES [job [copies] ]
This command changes the number of copies to be printed for the specified job.
SP-CREATE
SP-CREATE [form-queue [device-type [device-name] ] ]
SP-CREATE creates a form queue and assigns a device to it. (SP-DEVICE is used to assign a device to an existing form queue.) All three arguments are optional. If you omit an argument, SP-CREATE prompts you for an argument value.
The supported device-type values are: CACHE, DEBUG, GROUP, LPTR, NULL, PORT, PROG, TAPE, and UNIX®.
A device-type of DEBUG directs output to the user terminal (device 0), with 0.2 of a second delay between lines.
A device-type of GROUP creates a form queue group named form-queue. This form queue group contains those existing form queues that you specify as a series of device-name values (separated by blank spaces). You can specify a device-name of "", then later assign existing form queues to the form queue group using SP-DEVICE.
A device-type of PROG despools the print job to a process-private global, where it can be accessed by the specified MVBasic program or a ObjectScript program. You specify the name of the routine to call in device-name. Following the device-name routine name, you can specify one or more argument values to pass to this routine. Argument values are specified in the correct order, separated by blank spaces. The PROG process-private global contains the spooled job data, including leading and trailing form feeds, banners, preamble and postamble. This process-private global also includes the following subscripts:
A device-name must exist and be known to the system. When device-name is specified as a command argument, it must be specified as a quoted string. If you specify no device values at the prompts and press return, SP-CREATE creates an empty form queue.
SP-CREATE does not start the printing on that form queue. SP-START is used for this purpose.
SP-DELETE
SP-DELETE [joblist]
This command allows you to delete one or more print jobs. The optional joblist argument accepts a list of jobs to delete separated by spaces, as shown in the following example: SP-DELETE 66 68 71. You can also delete a range of print jobs, as shown in the following example: SP-DELETE 66-70. If you omit the joblist argument, SP-DELETE prompts you for a print job list.
SP-DEVICE
SP-DEVICE [form-queue [device-type [device-name] ] ]
This command allows you to:
(SP-CREATE is used to create a form queue and assigns a device to it.)
All three arguments are optional. If you omit an argument, SP-DEVICE prompts you for the argument value. The form-queue default is STANDARD. The supported device-type values are: CACHE, DEBUG, GROUP, LPTR, NULL, PORT, PROG, TAPE, and UNIX®.
A device-type of DEBUG directs output to the user terminal (device 0), with 0.2 of a second delay between lines.
A device-type of PROG despools the print job to a process-private global, where it can be accessed by the specified MVBasic program or a ObjectScript program. You specify the name of the routine to call in device-name. Following the device-name routine name, you can specify one or more argument values to pass to this routine. Argument values are specified in the correct order, separated by blank spaces. The PROG process-private global contains the spooled job data, including leading and trailing form feeds, banners, preamble and postamble. This process-private global also includes the following subscripts:
The device-name must exist and be known to the system. The device-name of a printer must be prefaced by |PRN|. When device-name is specified as a command argument, it must be specified as a quoted string. Any change in device name assignment takes effect when the despool process starts writing a new print job; it will not affect a print job midway through.
The following example shows several invocations of SP-DEVICE:
USER:SP-DEVICE STANDARD "|PRN|HPLJ80"
USER:SP-DEVICE CANON CACHE "|PRN|Canon MP530:(/WRITE:/APPEND:/DATATYPE="TEXT"):0"
USER:SP-DEVICE HP20 CACHE "|PRN|\\MACHINE\HP32:wan:0"
USER:SP-DEVICE FILEOUT CACHE E:\DATA\FILES:wa
SP-DISPLAY
SP-DISPLAY job1/formqueue [job1/formqueue [...jobn/formqueue]]
This command provides detailed information on the specified jobs or form queues. SP-DISPLAY is a synonym for SP-VERBOSE.
SP-EDIT, SP.EDIT
SP-EDIT [job[-job]] 

SP.EDIT [job[-job]] {L} {MD} {MS}
This command allows an administrator to manipulate spooler jobs. The SP-EDIT form is similar to the jBase, Pick, and Reality implementations. The SP.EDIT form is similar to UniVerse.
SP-EDIT
The SP-EDIT command allows you to edit pending print jobs. It is called from the command line as
SP-EDIT [JOB[-JOB]]
which allows editing of the characteristics of a single job or a range of jobs. Once invoked, the administrator enters a series of commands which are applied to the identified jobs. The available commands are:
Command Description
nn Moves the line pointer to line nn and displays that line in the print job.
+nn Moves the line pointer down nn lines and displays that line in the print job.
–nn Moves the line pointer up nn lines and displays that line in the print job.
A Repeat the previous “locate” command.
B Move line pointer to the bottom of the print job.
CP Moves the line pointer to the same position as the despooling position. This allows you to easily move to where the last line that was printed.
Dnn Moves the line pointer down nn lines and displays that line in the print job.
EX Exit editing this print job.
EXK The EXK command is similar but exits editing ALL print jobs that were specified.
FD Delete the print job.
HELP Display the help screen.
HEX Toggles the display of the lines of data from normal displayable characters to display of the lines of data as the hexadecimal value of each character.
L List a single line and advance the line pointer Lnn.
Lnn List nn lines of the print job and advance the line pointer.
L{nn} {str} Locate all occurrences of the string “str” in the print job starting at the current line position.
N{nn} Moves the line pointer down nn lines and displays that line in the print job.
N{nn}P Moves the line pointer down by nn pages and displays that page in the print job.
P Display a screen of data.
Pnn Display a screen of data, but first of all move the line pointer to page nn.
SP Sets the despool position to whatever the line pointer currently is positioned at. (This is a good way of restarting a print job at a different position.)
T Move line pointer to top of print job.
U{nn} Moves the line pointer up nn lines and displays that line in the print job.
U{nn}P Moves the line pointer up nn pages and displays that page in the print job.
W Display the previous screen of lines in the print job.
SP.EDIT
The SP.EDIT command allows you to perform simple administration on pending print jobs. It is called from the command line as
SP.EDIT [JOB[-JOB]] {L} {MD} {MS}
which allows editing of the characteristics of a single job or a range of jobs. If no jobs are specified, the commands apply to ALL jobs. The meaning of the command options are:
Option Description
L Display the first 512 characters of each selected job in turn.
MS The selected jobs will be set to spool. This changes the setting for any jobs that were set to SKIP. If there is an active despooller process running, all existing jobs are now candidates to be printed.
MD The select jobs will be deleted from the spooler.
If none of the options is specified on the command line, the characteristics of each selected job will be displayed in a form similar to
------- Details of Print Job # 45 in ^MV.SPOOL("45") -------
 
Form queue number :              00000
Form queue name :                STANDARD
Job status :                     CLOSED
Time of last status change :     Dec 08 2006 16:22:29
Number of lines in job :         6
Number of pages in job :         1
Time job created :               Dec 08 2006 16:22:29
Time job closed :                Dec 08 2006 16:22:29
Number copies to print :         1
Namespace of job creator :       %SYS
Account name of job creator :    SYSPROG
Username of job creator :       Greg
Port number of job creator :     5700
Despool page position :          0,0
Options :                        HOLD, INFORM, SKIP
The administrator is then prompted for a series of commands drawn from the following list:
Option Description
D Delete the print job.
E Edit the print job; begin a session similar to the SP-EDIT command for that print job so the administrator can examine and further manipulate the print job.
N Do not display anything from the print job.
S Set the status of the print job to be ready to be spooled. That is, remove any SKIP option from the print job. If a despool process is running, this print job becomes eligible for printing.
X Exit this print job and all subsequent print jobs you might have specified.
Y Display the first 512 characters of each selected job in turn.
SP-EJECT
SP-EJECT [pages]
This command creates a print job that begins with the specified number of blank pages. It spools the specified number of form feeds (page ejects). The optional pages argument must be an integer from 0 through 10. The default is 1.
SP-FORM
SP-FORM [old-form-queue [new-form-queue] ]
Change the name of a form queue. The form queue number remains the same.
SP-FQDELETE
SP-FQDELETE [form-queue]
Deletes a form queue and all the jobs on the queue. If there are any print jobs currently being printed, it will leave that print job as-is and not delete the form queue.
If you use SP-FQDELETE to delete a form queue which was a member of a form queue group, the form queue is deleted from the form queue group. Therefore, if you re-create the same form queue, you will need to add it again to the form queue group.
SP-GLOBAL
SP-GLOBAL [global-name] [(S]
SP-GLOBAL without an operand displays the name of the spooler table global for the current account. SP-GLOBAL with an operand changes the name of the spooler table global for the current account.
By default, the name of the global (and therefore the spooler table) is ^%MV.SPOOL, which is a system-wide global. Thus by default, all users share the same spooler table. SP-GLOBAL changes the name of the global where output will be collected for the current account. This allows each account to maintain a separate global, or for multiple accounts to share a global.
The global-name argument must be a syntactically valid Caché global variable name. Caché global variable names begin with the ^ character. SP-GLOBAL rejects a global name that fails global naming conventions with an appropriate error message. For further details on naming conventions for globals, refer to the “Variables” chapter of Using Caché ObjectScript.
The global-name should be either a nonexistent global or an existing MultiValue spooler global. If global-name refers to an existing data global or a MultiValue file, SP-GLOBAL displays an appropriate error message, then prompts you before proceeding, as shown in the following examples:
Existing global:
USER:SP-GLOBAL ^MYGLOBAL
Warning, the global ^MYGLOBAL already contains non-spool data.
If you continue, this data will be lost.
Do you wish to continue (Y/N) ?
Existing MultiValue file:
USER:CREATE-FILE MYSPOOLER
USER:SP-GLOBAL ^MYSPOOLER
Warning, the global ^MYSPOOLER is already allocated to the MV file MYSPOOLER.
If you continue, this file will be deleted.
Do you wish to continue (Y/N) ?
You can use the (S letter code option to suppress this prompt and assign the specified global as the spooler table.
The following example sets the Caché global ^SPOOLER in the namespace ADMIN as the spooler table for the current namespace GREG. Because Caché namespace names map to MultiValue account names, this means that all future users of account GREG will use SPOOLER in account ADMIN:
GREG:SP-GLOBAL ^|"ADMIN"|SPOOLER
Setting spooler global name to '^|"ADMIN"|SPOOLER'
The name of the global is part of the account metadata. It persists once set, so it remains set for all future logins for that user until explicitly changed.
SP-JOBS
SP-JOBS
The SP.JOBS command shows the status of print jobs queued to the spooler, and prompts you to enter a numeric action code to control a specified print job. It lists jobs in the sequence in which they were created, with the most recently created job shown first. SP.JOBS lists the job number, the queue name, the line number, the account name, the date and time created, the status, and the number of pages printed.
Print jobs are assigned sequential integer numbers. Once a day Caché MultiValue resets the assignment sequence to 1, so that print job numbers can be reused. However, numbers already assigned to pending print jobs are skipped over. For example, if the job number sequence is reset when there are pending print jobs numbered 1, 2, and 4, new print jobs will be assigned job numbers 3, 5, and so forth.
The following action codes allow manipulation of print job options and status.
No. Name Description
1 MOVE FORM QUEUE Move all jobs from one form queue to another. Same as the SP-MOVEQ command.
2 MOVE PRINT JOB Move a print job from one form queue to another.
3 CHANGE OPTIONS Modify the options associated with a print job.
4 CHANGE #COPIES Alter the number of copies of the specified job printed.
5 DELETE JOB Remove the jobs listed from the queue.
6 STOP PRINTING Stop printing on a form queue once the current job has completed and stop the despool process. Same as the SP-STOP command.
7 RESUME PRINTING Resume printing on a form queue that has been suspended with the SP-SUSPEND command (or option 9). Same as the SP-RESUME command.
8 EDIT PRINT JOB Add of remove pages from the given print job.
9 SUSPEND PRINT Suspend printing on a form queue. Same as the SP-SUSPEND command.
10 CLOSE JOB Close the specified print job.
11 SP-STATUS Changes the menu to that provided by the SP-STATUS command.
12 KILL PRINTING Kill printing immediately (even mid-job) and stop the despool process. Same as the SP-KILL command.
14 CLEAR QUEUE Delete all inactive print jobs on the form queue. Same as the SP-CLEAR command.
16 VERBOSE DISPLAY Given a job number, display the details about the job in verbose mode.
98 FILTER/SORT Allows for filtering (using the WITH clause) and sorting (using the BY clause).
99 EXIT Exit the program.
SP-KILL
SP-KILL [form-queue]
This command will kill printing of the current job on the form queue and then stop the despool process. The difference between this command and SP-STOP is that SP-STOP waits for the current job to finish printing, this one does not. You can specify * as the form queue name/number in which case we kill all running print despool processes.
SP-LOOK
SP-LOOK
Displays the assigned print channels with their form queue numbers (Q#), form queue names, specifications, number of copies to print (P#), and their assignment options. SP-ASSIGN assigns form queues and their options to a print channel. SETPTR assigns the Width, Lines, Top, and Bot specifications to a print channel. The SP-LOOK option keywords correspond to the SP-ASSIGN letter codes as follows:
SP-LOOK SP-ASSIGN
AUX A
COPIES n printnum
HOLD H
INFORM M not assigned
KEEP O
SKIP S
UNPROTECT U
SP-MOVEQ
SP-MOVEQ [from-form-queue [to-form-queue] ]
This command moves all the jobs from one form queue to another. Any job that is currently being printed is not moved.
SP-NEWTAB
SP-NEWTAB
This command completely re-initializes all form queues and adds a single default form queue called STANDARD. All print jobs and form queues are lost. SP-NEWTAB kills the current spooler global, as assigned by SP-GLOBAL. By default, the name of the MultiValue spooler global is ^%MV.SPOOL, which is a system-wide global. Thus by default, all users share the same spooler global.
If you use SP-GLOBAL to change the spooler global to another value (for example, the Caché general-purpose ^SPOOL spooler global) then you should be careful using SP-NEWTAB to avoid deleting non-MultiValue spool jobs.
SP-NEWTAB is performed independent of transaction status.
SP-OPEN
SP-OPEN
This command causes any new print job to remain open until either the user logs off or until the SP-CLOSE command is executed. It has the same effect as using the O option in the SP-ASSIGN command or the OPEN or KEEP option in the SETPTR command.
SP-OPTS
SP-OPTS [job [options] ]
This allows you to change the options on a job. The options are those items that can appear in position 7 of the SETPTR command: HOLD, SKIP, BANNER and so on.
SP-PAGESIZE
SP-PAGESIZE form-queue [width [ depth [ topmargin [ bottommargin]]]]
The SP-PAGESIZE command defines the page size for a MV spooler form queue. These values that can be set are page width , page depth, top margin and bottom margin. When a form queue is assigned using either SETPTR or SP-ASSIGN, these values will be used as necessary. You can delete these values by executing the SP-PAGESIZE with all the values set to 0.
The SETPTR command also allows defining a page width, depth, top and bottom margin. If these values are omitted in SETPTR, and the form queue has values set by SP-PAGESIZE, then these are the values will be used.
SP-POSTAMBLE
SP-POSTAMBLE form-queue subroutine
Sets the name of the subroutine name to be called after a job finishes printing on the named form queue.
SP-PREAMBLE
SP-PREAMBLE form-queue subroutine
Sets the name of the subroutine name to be called before a job begins printing on the named form queue. See Form Queue Control for a discussion of the preamble.
SP-PURGEQ
SP-PURGEQ [form-queue [job-list]]
This command removes jobs in the list from the specified form queue. The job-list is made up of a space-separated list of job numbers, or job number ranges, for example, “6–11”. Use “*” to remove all jobs from the queue.
SP-RESUME
SP-RESUME [form-queue]
If a despool process has been suspended with the SP-SUSPEND command, then this will resume the printing.
SP-SHOW
SP-SHOW job1/formqueue [job1/formqueue [...jobn/formqueue]]
This command provides detailed information on the specified jobs or form queues. SP-SHOW is a synonym for SP-VERBOSE.
SP-SKIP
SP-SKIP [form-queue [[lead-]trail] ]
Defines how many pages to skip after and (optionally) before printing a job. You can specify an integer number of lead leading form feeds before a print job and trail trailing form feeds after a print job. For example, SP-SKIP myqueue 1-3. If you specify a single integer, it defines the number of trailing form feeds, with a default of zero leading form feeds.
SP-START
SP-START [printer-name | *] [(B | F | I)] [(L)]
The SP-START command starts a despool process. This despool process monitors the spooler form queue and sends jobs from the spooler to the printer.
If you specify no argument, you are prompted to specify a form queue name. An * argument defaults to the STANDARD form queue. If you supply *, Caché will try to start all the defined printers.
By default, SP-START runs despool as a background process. To run despool as an interactive process, specify (I). To run despool as a background process, specify (B) or specify no letter option. To start despool as a foreground process which occupies a terminal, specify (F). The (F) option is useful for debugging, as described in Debugging the Despool Program.
The (L) option logs some of the activities of the despool process to the MultiValue log file, located at Cache/mgr/mv.log. You also can use the %SYS.System.WriteToMVLog() method to write to the mv.log file. Refer to the TRAP-EXCEPTIONS command for further details on mv.log.
To start printer spoolers as part of Caché start-up, do the following:
  1. Write a paragraph in the voc of someaccount that starts the printers:
       0001 PA
       0002 SP-START PRINTER1 CACHE |PRN|PRINTER1
       0003 SP-START PRINTER2 CACHE |PRN|PRINTER2 
  2. Have Caché %ZSTART schedule a background job to run this using the MV command:
    ZN "someaccount" MV "PHANTOM START.PRINTERS"
    %ZSTART is an ObjectScript routine you create and save (%ZSTART.mac) in the %SYS namespace. For further details, refer to Customizing Start and Stop Behavior with ^%ZSTART and ^%ZSTOP Routines.
SP-STATUS
SP-STATUS
The SP-STATUS command shows the status of the currently defined spooler form queues. It then prompts you to enter one of the following numeric action codes to control a queue or printer assignment.
No. Name Description
1 CREATE FORMQUEUE Create a new form queue. Same as the SP-CREATE command.
2 CHANGE QUEUENAME Change the name of the form queue. Same as the SP-FORM command.
3 PAGE SIZE  
4 CHANGE DEVICE Change the device associated with an existing form queue. Same as the SP-DEVICE command.
5 CHANGE PAGE SKIP Define how many pages to skip at the start of despooling a print job. Same as the SP-SKIP command.
6 LIST PRINT JOBS Changes the menu to that provided by the SP-JOBS command.
7 DELETE FORM QUEUE Delete a form queue and all the print jobs that were in that queue. Same as the SP-FQDELETE command.
8 VERBOSE DISPLAY Displays detailed information about the specified form queues.
9 DESPOOL CONTROL Changes the new page and/or new line control character sequences. Same as the SP-CONTROL command.
10 PURGE Removes jobs from the form queue.
98 FILTER/SORT Allows for filtering (using the WITH clause) and sorting (using the BY clause) of information.
99 EXIT Exit the program.
SP-STOP
SP-STOP [printer-name | * ]
The SP-STOP command stops printing on the printer at the end of the current job and then stop the despool process. Stopping a despool process causes jobs to wait on the spooler form queue and not be sent from the spooler to the printer.
If you specify no argument, you are prompted to specify a form queue name. An * argument defaults to the STANDARD form queue. Specifying * will stop all executing print spool jobs.
SP-SUSPEND
SP-SUSPEND [form-queue]
This command will suspend printing of a job. The despool process simply loops waiting for a SP-STOP, SP-RESUME or SP-KILL command to be issued.
This command is useful so the operator can, for example, adjust the printer on a long print job. If the operator notices a problem (ink running out, paper becoming skewed) the operator can suspend the printing, correct the problem, reposition the print job to where the problems first began and then use SP-RESUME to continue printing.
Repositioning the print job follows these steps:
For example, the following transcript shows repositioning print job 2 , currently printing on the STANDARD form queue, to resume at line 402:
USER:SP-SUSPEND STANDARD
SUSPEND command initiated on form queue STANDARD running on job 2508
USER:SP-EDIT 2
PRINT JOB # 2
WARNING: Job status is PRINTING
TOI
.401
000401 XXXX YYYY ZZZZZZ aaaaa bbbbb cccc
.SP
Print position set to 402,0
.EX
USER:SP-RESUME STANDARD
RESUME command initiated on form queue STANDARD running on job 2508
USER:
SP-SWITCH
SP-SWITCH [new-form-queue [job] ...
The SP.SWITCH command allows the administrator to switch one or more print jobs to the specified spooler form queue.
If you specify no arguments, you are prompted to specify a form queue name and one or more print jobs.
SP-TESTPAGE
SP-TESTPAGE [device | form-queue]
This command generates a standard test page and sends it to the designated destination.
The standard test page consists of the block letters “Cache Test Page”, followed by the Caché version string, the date and time that the test page was written, the output device name (for example |PRN|), and the Cache I/O name (for example |TRM|:|5740).
SP-TESTPAGE performs this test page operation using the following steps:
  1. Creates a temporary form queue.
  2. Adds a test page as a job to that form queue.
  3. Initiates a despool process using SP-START.
  4. Waits for the job to finish printing (or for timeout).
  5. Stops the despool process using SP-STOP.
  6. Deletes the temporary form queue.
Accordingly, the output of a SP-TESTPAGE command looks something like the following:
USER:SP-TESTPAGE File
Form queue STANDARD created as form number FQ00000000 in global ^%MV.SPOOL
Temporary form queue 'SPTESTPAGE_4616' created 
Test print job number 1 created, starting despool process 
Spooler STARTED in BATCH mode on form queue SPTESTPAGE_4616 at job 10012 
The test page appears to have printed successfully. 
STOP command initiated on form queue SPTESTPAGE_4616 running on job 10012 
Temporary form queue 'SPTESTPAGE_4616' deleted 
Full log written to file c:\intersystems\cache\mgr\mv.log 
USER:
SP-VERBOSE
SP-VERBOSE {job|formqueue} [{job2|formqueue2} [...]]
This command provides detailed information on the specified print jobs or form queues. It allows you to supply one or more print job numbers or form queue identifiers (form queue names or form queue numbers as displayed by the LISTPTR command) for verbose display. If specifying multiple print jobs or form queues, separate them with blank spaces.
If you specify no arguments, you are prompted to specify a print job number or form queue name (or number).
The following is a print job display:
USER:SP-VERBOSE 5 
  
------- Details of Print Job # 5 in ^%MV.SPOOL("5") ------- 
  
Form queue number : FQ00000000 
Form queue name : STANDARD 
Job status : CLOSED 
Time of last status change : Mar 08 2011 13:53:41 
Number of lines in job : 10 
Number of pages in job : 1 
Time job created : Mar 08 2011 13:53:41 
Time job closed : Mar 08 2011 13:53:41 
Number copies to print : 1 
Namespace of job creator : USER 
MV Account name of job creator : USER 
OS Username of job creator : glenn 
Cache Username of job creator : UnknownUser 
Port number of job creator : 20 
Despool page position : 0,0 
Unique Job Identifier : 12 
System name : DELLHOME 
IP Address : 127.0.0.1 
Cache Instance : DELLHOME:CACHE 
Options :
The following is a form queue display:
USER:SP-VERBOSE STANDARD
 
------- Details of form queue STANDARD in ^%MV.SPOOL("FQ00000000") -------
 
Form queue number :              FQ00000000
Form queue name :                STANDARD
Time formq created :             Mar 08 2011 10:36:26
Status of formq :                INACTIVE
Namespace of formq creator :     USER
Account name of formq creator :  USER
Username of formq creator :     glenn
Number of jobs on formq :        0
Job number being despooled :     --none--
Job ID of despool process :      --none--
Device name for despool :        |PRN|DOC2
Leading and trailing page skips :1
Notional device type :           CACHE
Despool job pre-amble routine :  --undefined--
Despool job post-amble routine : --undefined--
Page Size :                      --undefined--
Despool control chars :          FF,CR_LF
USER: