Caché I/O Device Guide
Spool Device
[Back] [Next]
Go to:

Caché lets you send print output directly to your printer or screen, or retain it in a spool global for printing at a later time. Caché spooling is independent of the spooling performed by your operating system.

Spooling in Caché is a technique that lets you automatically save the output of a program in the ^SPOOL subscripted global instead of printing it immediately. You can print the output later by sending the contents of the ^SPOOL global to the printer. This chapter describes two ways of using this spooling facility: using Caché ObjectScript commands (OPEN, USE, WRITE, CLOSE), or using the %IS and %SPOOL utilities.
Opening and Using the Spool Device
To send output to the spool global in your current namespace, you open the spooler and specify it as your output device.
The spooler is a predefined device provided with Caché. It is assigned device number 2 in the device table. This device number can be used to identify the spooler device in OPEN, USE, and CLOSE commands.
You can access spooler device information through the Management Portal. Select [Home] > [Configuration] > [Device Settings] > [Devices]. Here you will find both device 2 and a device named SPOOL. By default, these are both mapped to the same physical device (device 2) and have the same option values.
When you set the Caché spooler as the current device, Caché stores any output sent to Device 2 in the global ^SPOOL in your current namespace. Each line in ^SPOOL is in a separate global node.
There are two ways to open the Caché spooler and set it as the current output device:
OPEN and USE Commands for Spooling Device
You can open the spooling device directly by issuing OPEN and USE commands to that device.
OPEN 2:(doc_num:index)
OPEN Positional Parameters for Spooling
Parameter Definition
doc_num The number of the spool document (file) you want to open. Spool documents are stored in the ^SPOOL global. The default is 1.
index Line number, 1 or greater, within the spool document. The default is 1.
These are positional parameters. If you omit both parameters, they default to (1:1). You can set first parameter (doc_num) and omit the second (index), which defaults to 1. However, if you set the second parameter, you should specify the first parameter.
Caché uses these values to locate the lines you want to print. It treats the doc_num parameter as the first subscript of the ^SPOOL global. It treats the index parameter as the second subscript of the ^SPOOL global.
USE Command
When you issue USE 2 for device 2 after the command OPEN 2:(doc_num:index), Caché sends any subsequent output to the spooler at ^SPOOL(doc_num:index). Each output line is stored as a separate global node within ^SPOOL.
WRITE Command
To write a line to the ^SPOOL global, issue a WRITE command, ending with a line terminator character. For example:
   /* Writing to the ^SPOOL global */
   OPEN 2 
   USE 2 
     WRITE "First line of text",!
     WRITE "Second line of text",!
   CLOSE 2

   /* Displaying the ^SPOOL global */
   WRITE ^SPOOL(1,1),^SPOOL(1,2)
Each line ends with a line terminator (the exclamation mark) and is stored in a separate global node.
However, in producing a single print line, you may want to use several WRITE commands; if a WRITE does not contain a line terminator character, the next WRITE command appends to the same print line. Both write to the same global node. This line is held in a buffer and not written into the spool global until either a line termination character is issued, or the spooler device is closed.
The following example writes one global node when CLOSE is issued:
   /* Writing to the ^SPOOL global */
   OPEN 2 
   USE 2 
     WRITE "First half of line "
     WRITE "Second half of line"
   CLOSE 2

   /* Displaying the ^SPOOL global */
   WRITE ^SPOOL(1,1)
The line terminator character is commonly the ! (exclamation mark) WRITE command code character. This is equivalent to a carriage return (ASCII 13) and a line feed (ASCII 10). To terminate a line, both of these control characters are necessary. Issuing just a carriage return (ASCII 13) causes the carriage return to be concatenated into the line node, rather than initiating a new line node. In Caché Terminal, a line of this type displays as an overwrite of the text before the carriage return, by the text following it.
The following example writes only two line nodes in the ^SPOOL file:
   /* Writing to the ^SPOOL global */
   OPEN 2
   USE 2
     WRITE "XXXX",!
   CLOSE 2

   /* Displaying the ^SPOOL global */
   WRITE ^SPOOL(1,1),^SPOOL(1,2)
For more information, see the OPEN, USE, WRITE, and CLOSE commands in the Caché ObjectScript Language Reference.
Spooling and Special Variables
When writing to ^SPOOL, Caché continually updates the $X and $Y special variables. $X indicates the number of characters written to the current index line, and $Y contains the number of lines written during the current OPEN. Note that the value of $Y is not necessarily the same as the node index. For example:
   /* Writing to the ^SPOOL global */
   OPEN 2:(2:3)
   USE 2
     WRITE "Hello " SET x1=$X,y1=$Y,z1=$ZA
     WRITE "world",! SET x2=$X,y2=$Y,z2=$ZA
     WRITE "Good to see you",! SET x3=$X,y3=$Y,z3=$ZA
   CLOSE 2

   /* Displaying the ^SPOOL global */
   WRITE ^SPOOL(2,3),^SPOOL(2,4)
   WRITE !,"$X=",x1," ",x2," ",x3
   WRITE !,"$Y=",y1," ",y2," ",y3
   WRITE !,"$ZA=",z1," ",z2," ",z3
In this example, the first WRITE sets $X=6 (the current column number) and the second and third WRITE both set $X=0 (because of the line returns). The first WRITE sets $Y=0, the second $Y=1 (because of the line return), and the third $Y=2. Note however, that the lines that are being written are ^SPOOL(2,3), and ^SPOOL(2,4). To determine the index number, use $ZA.
Writing to a spool file sets the $ZA special variable with the next available index number. Thus, if you are writing to index=3, and do not include a line terminator, $ZA=3 (because the next WRITE continues writing to index 3), but if you do include a line terminator, $ZA=4.
The USE command sets $ZB to contains the doc_num of the spool file specified in the OPEN command.
The $IO special variable is not modified by writing to a spool file. Normally, $IO is reset by a USE command to contain the ID of the current device. However, when the device is an output-only device (such as the spooler), $IO continues to contain the ID of the current input device.
For more information, see the $X, $Y, $ZA, $ZB, and $IO special variables in the Caché ObjectScript Language Reference.
Closing the Spool Device
When you issue CLOSE for device 2, Caché automatically sets the node ^SPOOL(doc_num,2147483647) to store information about closing the spool document and the highest index number the output reaches.
Changing Namespaces
When you change namespaces with a SPOOL device left open, the spool device is closed automatically before the namespace change takes effect. The closing record in the ^SPOOL global is written into the correct database.
Abort Job Processing
If you open a spool device, dismount the current directory, then issue a HALT command or the Terminate($JOB) method of the SYS.Process class, Caché returns a persistent <PROTECT> error for subsequent attempts to access this spool device. To avoid this, change the namespace to automatically closes any open SPOOL device.
Viewing the ^SPOOL Global
Like any subscripted global, you can display lines from the spool file by issuing a WRITE command, as follows:
   WRITE "1st spool file node: ",^SPOOL(1,1),!
However, to view and edit the spool file itself, go to the Management Portal and select the Globals option. Select your current namespace (SAMPLES in the above example), locate the SPOOL global, then click data. This displays spool file data similar to the following examples.
In the following spool file, the (!) termination character ends each node line in the spool file. These termination characters are part of the spool file, concatenated to the text string as a $CHAR(13,10) (Return and Line Feed).
^SPOOL(1,1)=<<"First line of text"_$C(13,10)>>
^SPOOL(1,2)=<<"Second line of text"_$C(13,10)>>
In the following spool file, there are no line termination characters. The two WRITE commands wrote a single node line, which was terminated by the closing the spool file.
^SPOOL(1,1)=First half of line Second half of line
In the following spool file, return and line feed characters were explicitly coded in the WRITE commands. The $CHAR(10) line feed character initiates a new node line, and the $CHAR(13) return character is concatenated into these node lines.
The final line of the spool file is generated by Caché when you close the spool file. It consists of the literal 1,2147483647; the date and time in $HOROLOG format (59605,44993), and the number of lines in the spool file, including the final line.
You can edit or delete these spool file text lines. using the data display for the SPOOL global in the Management Portal Globals option.
Opening the Spooler Using the %IS Utility
%IS provides a convenient user interface at which a user can select the spool device, as well as any other device defined in the ^%IS global in the %SYS namespace. Using %IS, you can create a named spool file and write lines of text to that file. You can then print this spool file using the %SPOOL utility.
Only spool files opened using the %IS utility can be manipulated using the %SPOOL utility.
To create a spool file using %IS do the following steps:
  1. Invoke the %IS utility to open the spooler:
    >DO ^%IS
  2. At the “Device” prompt enter “2” or the mnemonic “SPOOL”.
  3. At the “Name” prompt, enter the name of the spool document (file). (Press Return at the “Name” prompt if you decide not to open the spool device.) If you enter the name of an existing spool document, %IS asks if it is correct, displays the last line of the file, and lets you choose where to add the new information. If you enter a new name, %IS asks if you want to create a new document. Press Return to create a new spool document, or enter “No” to redisplay the “Name” prompt.
  4. At the “Description” prompt, enter a one-line description. To increase readability, the description of the spooled document is on a separate line and wraps at column 70 if it is too long to fit on one line.
The following example writes the line “TESTING SPOOL FUNCTIONALITY” to the ^SPOOL global. IO is a variable that %IS sets to the device you specify at the “Device” prompt.
Device: 2
Name: SPOOLFILE not found 
Create new document 'SPOOLFILE'? Yes => <RETURN>
Description: This is my test spool file
Managing Spooled Documents Using %SPOOL
You manage spool files created when you access the Caché spool device with the %SPOOL utility. Caché spooling is independent from system spooling.
Spooling in Caché is a technique that lets you automatically save the output of a program in the global ^SPOOL instead of printing it immediately. You can print the output later by sending the contents of the global to the printer.
Use the %SPOOL utility to print, list, or delete spool documents in the ^SPOOL global in your current namespace. If you send a document to the spooler from a particular namespace, you must run the %SPOOL utility from that namespace to access it.
Only spool files opened using the %IS utility can be manipulated using the %SPOOL utility.
%SPOOL asks which spooling option you want. You can choose any of the three functions by entering either:
You can also enter a question mark (?) to display a list of these functions.
The following example shows how you select a spooling function, in this case, Print.
Spool function: ?
The available spool functions are:
  1) Print
  2) List documents
  3) Delete document
Enter the number or first few characters of the name of the
spool function you want.
Spool function: 1 Print
The following sections describe how to use the %SPOOL utility to perform the following tasks:
Printing with %SPOOL
Option 1 of the %SPOOL utility menu, Print, lets you print one or more documents in the ^SPOOL global on any device, resume printing an interrupted document, and handfeed single sheets of paper into a letter-quality printer. By sending output to the spooler, you release your terminal for other uses while the output device prints your document.
You can start printing either before or after the spool document is fully created. If the printer catches up to the new output, the print process pauses for five seconds, then prints all the output accumulated during that time. The print process knows when you have closed the spool document and finishes when the document is done.
As %SPOOL prints the document, it keeps track of the pages it has printed. It also creates a page index, so that you can sort through the document by page number and begin printing at the top of any page you choose.
If you stop printing (for example, by pressing ctrl-c during terminal output, or if your printer breaks), you can later resume at the top of the last partially printed page or at the top of any other page in the document. Note that Caché does not count form feeds at the start of the document as pages in the page count.
%SPOOL uses the term despool to mean print. There will be values in the Despool start-end column and on the description line only if the document has been printed (despooled).
Using the Print Function
  1. At the “Spool function:” prompt, enter 1.
  2. At the “Name:” prompt, enter a ? to display help text, enter ?? to list all existing spool documents in the current namespace, or enter the name of the spool document you want to print. %SPOOL confirms that this is the correct document.
  3. When %SPOOL asks you for the page where you want to start printing, press return to start at the first page, or enter any page number in the document. If you try to start printing at the top of a page the printing process has not yet reached, the following message displays: WARNING: Printing hasn't reached this point. After this warning, %SPOOL asks if you are sure you want to start printing on the page you selected. If you enter No, it returns you to the “ Start at page:” prompt. If you enter Yes to confirm the starting page, %SPOOL displays the first few lines of the page in question and reconfirms that this is the right page.
  4. You are prompted for the number of copies.
  5. %SPOOL lets you enter the names of other spool documents you want to print. When you respond to the “ Name:” prompt by pressing return, it asks you for the output device and its right margin. Enter this information to start printing.
    Note that %SPOOL issues a form feed after each page, whether you are printing on a screen or a printer.
The following example shows you how to print a document in the ^SPOOL global, in this case called SPOOLFILE. The document will print on the device called MYPRINTER.

Spool function: 1  Print 
Name: ??

#  Name        Lines   Spool start      Despool start-end
1  SPOOLFILE   1      30 Aug  2:23 pm    30 Aug  2:25 pm-2:25 pm
  This is my test spool file


1  SPOOLFILE    30 Aug 2003  2:23 pm  this is my test spool file
SPOOLFILE has 1 pages.
Is this correct?  Yes=>Y
Start at page:  1=>Y
How many copies?  1=>Y

Print spooled files on
Device: MYPRINTER RETURN Parameters: "WNS"=>
Free this terminal? Yes =>Y
Starting Job in background . . . started.

Spool function:
Listing Spooled Documents
Option 2 of the %SPOOL utility menu, List documents, displays a list of the documents currently spooled for the directory in which %SPOOL is running. If there is no Despool start-end value, the document has not yet been despooled (printed).
The description of each spooled document appears on one or more separate lines following the rest of the information about that document.
In the following example, the user selected Option 2. The display reveals two documents stored in the spooler. The first was stored on August 30 at 2:23 p.m. and printed the same day at 2:25 p.m. The second was stored on March 4 at 11:39 a.m. and printed the same day at 11:42 a.m.
Spool function: 2   List documents

# Name      Lines   Spool start     Despool start-end 
1 SPOOLFILE  1     30 Aug  2:23 pm  30 Aug  2:25 pm- 2:25 pm
  This is my test spool file

3 LONGFILE   1     04 Mar 11:39 am  04 Mar 11:42 am- 11:42 am 
  This is a very long description line that shows you what happens when you
have a long description. It shows you how the text wraps from line to line.
This particular description was made intentionally long, so as to wrap at least
Deleting Spooled Documents
Option 3 of the %SPOOL utility menu, Delete document, lets you delete one or more spool documents, When %SPOOL prompts you for a name, enter the name of the document you want to delete, or enter ?? to display the current spool documents for the namespace you are in. Enter a ? for help text.
%SPOOL confirms that this is the correct document, and that you want to delete it. If you answer “Yes,” %SPOOL deletes the document, and allows you to name other documents you want to delete.
The following example deletes the spooled document called SPOOLFILE.
Spool function: 3   Delete document       
Name: ??

# Name        Lines  Spool start        Despool start-end 
1 SPOOLFILE     1    30 Aug  2:23 pm  30 Aug  2:25 pm- 2:25 pm
  This is my test spool file


1 SPOOLFILE    30 Aug 2003  2:23 pm  this is my test spool file
SPOOLFILE has 1 pages.
Is this correct?  Yes=>Y
Delete SPOOLFILE? No=> Y [Deleted]