Spooler Commands

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.

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.

• BANNER name: item ID is always name. Each subsequent job overwrites the previous version of name.

• BANNER NEXT: item ID is an incremented number, P#0000_nnnn, where nnnn is incremented for each entry to &HOLD&, nnnn increments from 0001 through 9999.

• BANNER NEXT name: item ID is an incremented number, name_nnnn, where nnnn is incremented for each entry to &HOLD&. nnnn increments from 0001 through 9999.

• BANNER UNIQUE: item ID is an incremented number, P#0000_nnnn, where nnnn is incremented each time the SETPTR command is executed. nnnn increments from 0001 through 9999.

  In UniData emulation, BANNER UNIQUE is a synonym for BANNER NEXT.

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 [ (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 {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, using SP-ASSIGN with a numbered form queue automatically creates the form queue if it does not exist, and then assigns it. Named form queues, however, must first be explicitly created using SP-CREATE before being assigned with SP-ASSIGN. This SP-ASSIGN 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:

• =formidentifier

  Specifies a form queue identifier for print channel 0. formidentifier can be either a name or a number, as displayed by the LISTPTR command. By default, print channel 0 is named STANDARD.

• nn=formidentifier

  Specifies a form queue identifier for print channel nn. formidentifier can be either a name or a number, as displayed by the LISTPTR command.

• nn=

  Clears the existing form queue identifier from print channel nn.

• Fformname

  Specifies a form queue name for print channel 0. By default, print channel 0 is named STANDARD.

• Fformnum

  Specifies a form queue number for print channel 0. By default, print channel 0 is assigned form queue 0.

• Qformname

  Specifies a form queue name for print channel 0. By default, print channel 0 is named STANDARD.

• printnum

  An integer that specifies the number of copies to print. The default is 1. When no other formspecs item is specified, printnum changes the number of copies for print channel 0. When specified with nn=formname, printnum changes the number of copies for the specified print channel. Print channel assignment and the number of copies must be separated by a blank space.

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:

• A – Auxiliary printing

• F – Create form queue

• H – Hold job after being printed

• K – Kill (clear) the form queue assignments for all print channels. Parenthesis required.

• M – Suppress the display of “Entry #” message when hold job created

• O – Keeps the print job open over multiple programs

• Q – Create form queue

• S – Suppress automatic printing when job created

• U – Unprotect the spool job

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 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 [form-queue]

This command clears all the jobs from the specified form queue.

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 [(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:

• SP-CONDUCT with no arguments (except the optional (V) verbose option) returns the current settings as the integer total of the bit positions. The verbose option lists the component bit positions that make up this integer total.

• SP-CONDUCT ? lists all of the available bit integers and their symbolic names.

• SP-CONDUCT nnn allows you to set bit positions for various spooler behaviors. You can specify a single nnn value or several nnn values separated by blank spaces.

  There are six ways to specify spooler behavior settings:

  • nnn: an integer that sets the specified bit positions. Any prior bit settings are eliminated. For example, 129 sets bits 1 and 128.

  • +nnn: a signed integer that sets a single specified bit position. All other bit positions remain unchanged. For example, +256 sets the 256 bit; it has no effect on other bit settings.

  • -nnn: a signed integer that resets (clears) a single specified bit position. All other bit positions remain unchanged. For example, –256 clears the 256 bit, setting it to 0; it has no effect on other bit settings.

  • +name: a keyword that sets a single bit position by symbolic name. All other bit positions remain unchanged. For example, +NO_INHERIT sets the 32 bit (see table below); it has no effect on other bit settings.

  • -name: a keyword that resets (clears) a single bit position by symbolic name. All other bit positions remain unchanged. For example, –NO_INHERIT clears the 32 bit, setting it to 0 (see table below); it has no effect on other bit settings.

  • DEFAULT: a keyword that resets all bit positions to the default settings for the current emulation.

The following are the available bit positions and their symbolic names:

These bit position values are additive. The default setting for each emulation is:

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 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 [job [copies] ]

This command changes the number of copies to be printed for the specified job.

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 an 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:

• ^||PPGMVDESPOOL("JOBNO") The original spooler job number.

• ^||PPGMVDESPOOL("GLOBAL") The name of the global with the original job.

• ^||PPGMVDESPOOL("FQNAME") The form queue name that held the job.

• ^||PPGMVDESPOOL("PARAMETERS") The list of parameters passed to the device-name routine.

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 [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 [form-queue [device-type [device-name] ] ]

This command allows you to:

• Change the device for an existing form queue. SP-DEVICE assigns the specified printer device to a spooler form queue. It assigns the form queue a form number (FQ) in the global ^%MV.SPOOL.

• Change the form queue list for an existing form queue group by specifying device-type GROUP. SP-DEVICE can assign multiple form queues to a form queue group. By default, SP-DEVICE overwrites any existing form queues in the form queue group. The (A letter code option causes it to append the specified form queues to the form queue group, rather than replacing them. The (R letter code option causes it to remove the specified form queues from the form queue group.

(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 an 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:

• ^||PPGMVDESPOOL("JOBNO") The original spooler job number.

• ^||PPGMVDESPOOL("GLOBAL") The name of the global with the original job.

• ^||PPGMVDESPOOL("FQNAME") The form queue name that held the job.

• ^||PPGMVDESPOOL("PARAMETERS") The list of parameters passed to the device-name routine.

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 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 [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.

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:

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:

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:

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 [old-form-queue [new-form-queue] ]

Change the name of a form queue. The form queue number remains the same.

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 [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

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.

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

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-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

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

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 [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 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 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 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 [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 [form-queue]

If a despool process has been suspended with the SP-SUSPEND command, then this will resume the printing.

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 [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 [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()Opens in a new tab 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

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.

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 [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:

• Suspend the despool process, if necessary, with the SP-SUSPEND command.

• Edit the print job with the SP-EDIT command (note: For legacy reasons the SP-EDIT and SP.EDIT commands differ, always use SP-EDIT for this task).

• Once in the edit, position the editor to the line you want to reposition at.

• In the editor execute the SP command.

• Restart the printer with the SP-RESUME command.

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 [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 [device | form-queue]

This command generates a standard test page and sends it to the designated destination.

• SP-TESTPAGE sends the test page to the standard print device, "|PRN|:(/WRITE:/APPEND:/DATATYPE="TEXT"):0".

• SP-TESTPAGE device sends the test page to the specified Caché print device. This can be in the form, "devicename", or optionally with an added open mode and timeout, for example, "|PRN|:rwn:2".

• SP-TESTPAGE form-queue sends the test page to the print device associated with the given form-queue. If the form queue is of type DEBUG, or the device name is NULL or DEBUG, then Caché will generate an error message.

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 {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: