Spooler Command Examples
A Simple Example
This example shows printing 3 lines of output on a Windows printer. The Windows name of the printer was HP7210.
Assign a printer device name to the default STANDARD form queue.
SOMEACCT:SP-DEVICE STANDARD CACHE "|PRN|HP7210" Form queue STANDARD created as form number FQ00000000 in global ^MV.SPOOL SOMEACCT:
This has the effect of creating a new spooler table in the Caché global called ^MV.SPOOL.
Now write to the spooler. The program TEST12 writes 3 lines to the default print spool form queue.
SOMEACCT:ED GBP TEST12 TEST12 4 lines long. ----:p 0001: PRINTER ON 0002: FOR I = 1 TO 3 0003: PRINT "Line ":I:" of 3" 0004: NEXT I Bottom at line 4. ----:FIBC "TEST12" filed in file "GBP". TEST12 [B0] Compilation completed. [241] 'TEST12' Cataloged. SOMEACCT:TEST12
At this point, an SP-JOBS will show the print job is now CLOSED and waiting to be printed.
SOMEACCT:SP-JOBS Dec 20 06 13:40:00 ^MV.SPOOL PRINT JOBS PAGE 1 OF 1 JOB QUEUE LINE ACCOUNT CREATED STATUS OPT PRINTED 1 STANDARD 1088 SYSPROG 20 Dec 13:39 CLOSED 0,0 OF 67,1 1. MOVE FORM QUEUE 6. STOP PRINTING 11. SP-STATUS 16. VERBOSE DISPLAY 2. MOVE PRINT JOB 7. RESUME PRINTING 12. KILL PRINTING 3. CHANGE OPTIONS 8. EDIT PRINT JOB 4. CHANGE #COPIES 9. SUSPEND PRINT 14. CLEAR QUEUE 5. DELETE JOB 10. CLOSE JOB 99. EXIT Enter action code / Page number (P#)
Start a despool process. These jobs run in the background and monitor the spooler tables. When they see a completed and closed print job, they write it to the printer.
SOMEACCT:SP-START * Spooler STARTED on form queue STANDARD at job 3076
If nothing appears on the printer:
-
Execute the SP-JOBS menu command and see if the job still exists on the form queue.
-
If the job exists, the SP-STATUS command displays the status of the STANDARD form queue. If the status displayed is I/O Error, an incorrect device name may be assigned to the form queue (see the SP-DEVICE command).
-
If the job has been removed and no longer exists, the despool process was able to send the job to the physical device. In this case, you may need assistance from your system administrator to determine what happened to the output.
Stop the despool process. This stage not really necessary, but shown for completeness. With SP-STOP, it will stop the background despool process and so further print jobs will simply wait on the form queue for further action.
SOMEACCT:SP-STOP * STOP command initiated on form queue STANDARD running on job 3076 SOMEACCT:
A SETPR Example
The following SETPTR command sets channel 3 to be a printer with a page 132 characters wide and 64 lines deep. Two lines are left blank at the top and bottom for margins. The print output is to be directed to the spooler (printing mode 1). Three copies of the output should be printed with a banner page of “FINAL” and an additional page ejected at the end of each copy.
SETPTR 3,132,64,2,2,1,AT HP7000, COPIES 3,EJECT,BANNER FINAL
An SP-JOBS Example
The SP-JOBS command displays a menu to display the print jobs and allows lots of manipulation of the jobs. The purpose of this section is just to talk about the options that are available. This is a sample SP-JOBS output and menu:
Dec 05 2006 13:56:55 ^MV.SPOOL PRINT JOBS PAGE 1 OF 3 JOB QUEUE LINE ACCOUNT CREATED STATUS OPT PRINTED 16 DEBUG 5700 SYSPROG 05 Dec 10:58 CLOSED H 6,3 OF 6,3 17 DEBUG 5700 SYSPROG 05 Dec 10:59 CLOSED H 6,3 OF 6,3 18 DEBUG 5700 SYSPROG 05 Dec 11:14 CLOSED H 6,3 OF 6,3 19 DEBUG 5700 SYSPROG 05 Dec 11:14 CLOSED H 6,3 OF 6,3 20 STANDARD 5700 SYSPROG 05 Dec 11:15 CLOSED 0,0 OF 9,1 21 DEBUG 5700 SYSPROG 05 Dec 11:15 CLOSED H 6,3 OF 6,3 22 DEBUG 5700 SYSPROG 05 Dec 11:16 CLOSED H 6,3 OF 6,3 23 DEBUG 5700 SYSPROG 05 Dec 11:16 CLOSED H 6,3 OF 6,3 24 DEBUG 5700 SYSPROG 05 Dec 11:22 CLOSED H 6,3 OF 6,3 25 DEBUG 5700 SYSPROG 05 Dec 11:22 CLOSED H 6,3 OF 6,3 26 DEBUG 5700 SYSPROG 05 Dec 11:22 CLOSED H 6,3 OF 6,3 1. MOVE FORM QUEUE 6. STOP PRINTING 11. SP-STATUS 16. VERBOSE DISPLAY 2. MOVE PRINT JOB 7. RESUME PRINTING 12. KILL PRINTING 3. CHANGE OPTIONS 8. EDIT PRINT JOB 4. CHANGE #COPIES 9. SUSPEND PRINT 14. CLEAR QUEUE 5. DELETE JOB 10. CLOSE JOB 99. EXIT Enter action code / Page number (P#)
The column marked OPT shows up to 3 characters, H, S, and U. If H is shown, the HOLD option is used (it won’t be deleted after printing); the S option indicates skip printing; the U option states that the output is unprotected, hence removing security.
Regarding the options:
An SP-STATUS Example
The SP-STATUS command shows the jobs in the queue and allows a single option:
Dec 14 2006 11:55:17 ^MV.SPOOL PRINT JOBS PAGE 1 OF 1
QUEUE NAME DEVICE STATUS #Q SKIP
STANDARD NO DEVICE 4
DEBUG DEBUG:0.1 INACTIVE 6 2
HP7200 HP7200 INACTIVE 5 1
1. CREATE FORMQUEUE 4. CHANGE DEVICE 7. DELETE FORM QUEUE
2. CHANGE QUEUENAME 5. CHANGE PAGE SKIP 8. VERBOSE DISPLAY
6. LIST PRINT JOBS 99. EXIT
Enter action code / Page number (P#)
An SP-AUX Example
To enable auxiliary printing, there are three mechanisms you can use:
-
Use the A option to the SP-ASSIGN command, for example:
USER:SP-ASSIGN 3=FORMNAME HSA
-
Use the AUX option to SETPTR:
USER:SETPTR 3,132,66,0,0,1,banner,hold,aux
-
Use the SP-AUX command to print an existing print job:
USER:SP-AUX 3-4 8
In cases 1) and 2), when a print job is created it will be built up on the spooler as usual. When the print job is closed for whatever reason, Caché will attempt to print the job on the printer attached to the user's terminal (the auxiliary printer). Once the job has been printed, it will behave as though it were a normal print job, That is, it will become ready for printing by any despool process (unless the SKIPJOB option was set), and may also be deleted.
In case 3), it allows you to print any job, or list of jobs, or range of list of jobs, to the printer attached to your own terminal. The use of the SP.AUX command does not affect the job in any way.
For example, the command
USER:SP-ASSIGN 4=FORMNAME HSA
sets print channel 4 to form queue FORMNAME, and sets the HOLD, JOBSKIP and AUX options. The AUX option means any print jobs are sent to the user's attached printer through the terminal. Once printed, it becomes a regular print job. The HOLD and JOBSKIP options mean it will not be despooled by any despool process but will be retained on the spooler form queue.
The SETPTR command is enhanced to support the AUX option as in
USER:SETPTR 4,132,66,0,0,1,hold,skip,aux
and is similar to the SP-ASSIGN example and sets the same options.
The SP-LOOK command is enhanced to show the AUX option, for example:
USER:SP-LOOK FORM QUEUES Chan Q# Q name Width Lines Top Bot P# Options 0 0 STANDARD 132 66 0 0 1 AUX, HOLD, INFORM, SKIP
The SP-VERBOSE command is similarly enhanced to show the AUX option:
USER:SP-VERBOSE 6
------- Details of Print Job # 6 in ^MV.SPOOL("6") -------
Form queue number : FQ00000000
Form queue name : STANDARD
Job status : CLOSED
Time of last status change : May 25 2007 14:41:03
Number of lines in job : 1
Number of pages in job : 1
Time job created : May 25 2007 14:41:03
Time job closed : May 25 2007 14:41:03
Number copies to print : 1
Namespace of job creator : USER
Account name of job creator : USER
Username of job creator : UnknownUser
Port number of job creator : 22
Despool page position : 0,0
Options : AUX, HOLD, INFORM, SKIP
And so is SP-JOBS:
USER:SP-JOBS
May 25 2007 14:42:26 ^MV.SPOOL PRINT JOBS PAGE 1 OF 1
JOB QUEUE LINE ACCOUNT CREATED STATUS OPT PRINTED
6 STANDARD 22 USER 25 May 14:41 CLOSED AHS 0,0 OF 1,1
In all cases, the terminal definition for the current terminal in use needs to support auxiliary printing, otherwise an error message is displayed.
The command strings to support this are the mc5 string (turns ON the auxiliary printer) and mc4 (turns OFF the auxiliary printer).
When a print job is created with the AUX option in effect, the print job will be tagged with the AUX flag, as shown in the SP-VERBOSE and SP-JOBS commands detailed earlier. While this flag is set, the despool process will not despool the job. Once a print job closes, and the print job has been printed to the users terminal, the AUX flag is reset and the despool process can continue.
If there is confusion why a print job won't print, it may be that it was created with the AUX flag but an error occurred before the job could be fully printed to the users auxiliary printer, hence the AUX flag is still set on the job. In this case, you can use the SP-OPTS command (or option 3 from the SP-JOBS menu) to reset the AUX option.
Examples Specifying An Output Device
As noted in the SP-CREATE and SP-DEVICE commands, there are three arguments:
-
FORM-QUEUE
-
DEVICE-TYPE
-
DEVICE-NAME
The FORM-QUEUE represents a logical collection point in the spooler for all output of a similar format.
The DEVICE-TYPE argument is present for compatibility and is not used at this time. However, it must be one of the following values: CACHE, DEBUG, LPTR, NULL, PORT, PROG, TAPE, UNIX®.
The DEVICE-NAME is the name of the physical device. Its form is operating system dependent. Any value acceptable to the ObjectScript OPEN command can be used. For example, on Windows systems, the device name looks like:
|PRN|printername
and on UNIX® systems, like:
/usr/bin/lp -dprintername:QW:3:
For UNIX®, a full path name is required for the device or program. For Windows printers, the sequence “PRN” must always appear in uppercase.
For Windows, using a shared printer across a network has additional requirements. These are described in Appendix A of this manual: Setting Up a Windows Shared Printer.
Writing to a Null Printer
At the time of installation, or after using the SP-NEWTAB command, Caché always creates a queue named STANDARD as queue #0. Since STANDARD is the default queue when a user enters the MV shell, this queue may end up with a lot of unwanted output. If no one starts a despool process on it, unwanted jobs fill up the spooler queue.
To deal with this issue, an instance can create a despooler process for a queue to send the output to the “null” device. On Windows, issue the command:
SP-DEVICE STANDARD CACHE NULL
On Linux systems, the following command is equivalent:
SP-DEVICE STANDARD CACHE /dev/null
As an alternative, the administrator may create a new queue, called “VOID” in this example, for this purpose:
SP-CREATE VOID CACHE NULL
Output that is destined to be discarded can be directed to this queue.
Writing to a UNIX®/Linux Printer
This command writes to the UNIX® device name /dev/usb/lp0 and uses the WN parameters to open the device in write mode and allow for the device to be new.
USER:SP-CREATE QNAME CACHE /dev/usb/lp0:WN
Writing to a Program on a UNIX®/Linux System
This command writes to the UNIX® spooler, the lp verb, specifies a destination queue on the UNIX® spooler, The QW parameters state to open a queue and send input to another process, and gives a 3 second timeout before it fails.
USER:SP-DEVICE QNAME CACHE /usr/bin/lp -dlaserjet:QW:3
Note that in UNIX® a full path name is required for the device or program.
Writing To A Printer On A Windows System
This command writes to the default printer:
USER:SP-DEVICE STANDARD CACHE "|PRN|"
while this one writes to a named printer:
USER:SP-DEVICE STANDARD CACHE "|PRN|HPLJ7210"
Depending upon the printer type and printer driver, you might find that the output goes to the Windows spooler but it is then lost by Windows. In this case, you need to open the Windows device in TEXT mode, as shown in the following example:
USER:SP-DEVICE CANON CACHE "|PRN|Canon MP530:(/WRITE:/APPEND:/DATATYPE="TEXT"):0"
Writing to a File on a UNIX® System
This command directs output to a file:
USER:SP-DEVICE FQNAME CACHE /tmp/fileout:WN
Debugging the Despool Program
The despool program is normally started with SP-START which starts a background job. This causes terminal output to be lost. An administrator can issue SP-START with the (F) option to start a despool process from the terminal prompt as a foreground job to aid in debugging problems.
In this mode, should an error occur, it will not trap automatically and clear held locks. Despool locks need to be cleared manually for this process. Use the Management Portal to look for locks for this process.
As a further debug tool, the device can be called DEBUG. In the following example, the administrator creates a form queue called FQDEBUG with a device specification of DEBUG:0.2, assigns themselves to the new print queue and does a simple LIST, hence creating a job to output. Then, using SP-START with the (F) option to start the despool process in foreground mode. This will then display to the screen the print jobs for the FQDEBUG form queues with a delay of 0.2 seconds between each line.
USER:SP-CREATE FQDEBUG CACHE DEBUG:0.2 USER:SP-ASSIGN =FQDEBUG USER:LIST VOC (P) USER:SP-START FQDEBUG (F)
