Working with spool files

To the typical MPE/iX user, the Native Mode Spooler makes it appear as though he or she has exclusive access to the printer. That is, whenever users need to print something, or if they stream a job that produces a printed report, they simply issue a command without checking to see if the printer is busy or not and the spooler handles the rest.

The way that the spooler manages shared access to a single printer is by creating a spool file that contains, among other information, the text of the report. The spooler adds this file to the spool queue for the printer (if the queue is open) and then sends the spool file to the printer when it reaches the top of the queue. Once the report is printed, the spool file is deleted from the queue (unless you explicitly choose otherwise), which means that a list of spool files typically is equivalent to a list of files waiting to be printed.

This section explains the types of spool files and shows how MPE/iX users can work with their own spool files. (The spooler allows members of the system adminstration staff, depending upon their assigned capabilities, to manipulate all individual spool files in the queue and the spool queue itself. This chapter does not explain spool management.) In the next section, you'll learn the different ways to view spool files.

Types of spool files

With the native mode spooler (NMS), the file system creates spool files as ordinary, permanent disk files. There are two kinds of spool files it creates, input spool files, which are always linked to the spool file directory, and output spool files, which may or may not be linked to the spool file directory. The NMS also creates a third kind of disk file, checkpoint files, which are used to assist in the printing of output spool files.

When the spooler generates these files, it automatically places them into the reserved account HPSPOOL. If you are the user who created the spool files, you may view and access them as if they were in your own group and account.

Three numeric codes designate the files as input spool files, output spool files, and checkpoint files. They are:

     input spool files

     output spool files

     checkpoint files

For more information, see the discussion of the BUILD command later in this chapter.

Input spool files

The spooler creates input spool files when you submit jobs or enter data either via command line input (i.e. issuing the JOB or DATA commands) or from a spooled input device. The spooler copies a streamed or input spooled job to an input spool file and MPE schedules the job. When the job logs on, the spool file becomes the job's input ($STDIN). See the JOB command in the MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-60115) for more information. Similarly, data are placed into an input spool file and can be accessed by the user.account specified in the DATA command. See the DATA command in the MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-60115) for more information.

The system creates input spool files in the IN group of the reserved account HPSPOOL. Input spool file names have the format Innnn.IN.HPSPOOL where nnnn is a number, for example, I235.IN.HPSPOOL. Because input spool files are always linked to the spooling subsystem, IN.HPSPOOL is the only place in the system containing input spool files. These files remain in IN.HPSPOOL until a job or process uses them or you delete them with one of the following methods:

ABORTJOB for a job's $STDIN spool file.
SPOOLF with the DELETE parameter for input spool files created with the DATA command.
A START NORECOVERY system startup deletes all JOB and DATA input spool files.




	NOTE: Job input spool files have a one-to-one correspondence with job master table (JMAT) entries. The JMAT is rebuilt for updates and `START NORECOVERY`. Whenever an update or `START NORECOVERY` occurs, the system purges all input spool files. Input spool files are only `recovered` during a `START RECOVERY` startup because the JMAT is only recovered at that time.

Output spool files

Output spool files normally reside in the OUT group of the HPSPOOL account and, unless you explicitly delete them, remain there until they print. You may use the ;SPSAVE parameter with the FILE, JOB, and SPOOLF ...;ALTER commands to leave your spool file in OUT.HPSPOOL after all copies of the file print. Then you may copy the saved spool file into your own group and account so that you do not have to run the generating application again. You may not use the ;SPSAVE parameter to save a private output spool file.

Output spool file names have the format Onnnn.OUT.HPSPOOL where nnnn is a number, for example, O46.OUT.HPSPOOL.

The OUT.HPSPOOL group contains only linked output spool files. If you copy an output spool file from OUT.HPSPOOL to your account, the copy is not linked into the spooling subsystem. If you issue the SPOOLF command with the parameters PRINT and DEV on the copy, another copy is made in OUT.HPSPOOL and this copy is linked.

You can also create unlinked output spool files by using the BUILD or FILE commands with the ;SPOOL parameter or with the HPFOPEN intrinsic.

Checkpoint files

Checkpoint files are companions to output spool files that help the spooler recover from device problems such as power failure and paper jams. Checkpoint files also help a suspended spooler resume producing output. There is one checkpoint file per output spool file for each device that prints the spool file.

The output spooler creates the checkpoint file at the time it begins to print an output spool file, not before. The checkpoint file is automatically deleted when you or the spooler delete the output spool file from the HPSPOOL account or after a spool file that is saved with the ;SPSAVE parameter has its last copy printed.

The naming convention used for a checkpoint file is either of the following:

   Cnnnnn.device_name.HPSPOOL



   or



   Cnnnnn.Dmmmmmmm.HPSPOOL

Where Cnnnnn is the numerical value of the spoolid of the corresponding spool file preceded by a "C", and Dmmmmmmm is the logical device number (with leading zeros as required), preceded by a "D". Refer to the "File naming convention" section in appendix D for more information on naming a checkpoint file.

Checkpoint files are created for every output spool file, but they are only used on CIPER protocol printers.

Private and nonprivate spool files

All input spool files are automatically created private. By default, an output spool file is nonprivate, but you may choose to make it private for greater data security.

Private spool files

Private output spool files differ from regular nonprivate spool files in the following ways:

Since they are level 2 privileged files, you may access them only by processes that call the HPFOPEN intrinsic while running at level 2 privileged mode. This means that the MPE/iX commands PURGE and PRINT fail. Level 3 programs such as FCOPY or your favorite editor and the FOPEN intrinsic can not open a private file.
You may not save a private file by using the ;SPSAVE option with the SPOOLF ...;ALTER command.
Users with SM capability cannot store private spool files, but they can use the PRINTSPF utility to print the files, and, if necessary, alter the target device.
You may not copy, browse, or open a private output spool file (or an input spool file) as a disk file.
You may not alter the number of copies.
The only other control that you have over a private output spool file is to alter its priority, to defer or not defer it, or to delete it completely. You must have access to the spool file—according to the guidelines for nonprivate spool files—for this control.

Nonprivate spool files

You may access nonprivate spool files according to the following guidelines:

If you have SM or OP capability, or if you are logged on at the system console, you may access any nonprivate spool files. This means that you can read, delete, or alter a spool file using either the NMS commands and intrinsics or standard MPE/iX commands and intrinsics.
If you have AM capability, you may similarly access any spool file whose creating user is in your account.
If you are the creating user, you may access spool files that you create.

If you have read access to nonprivate spool files, you may store and restore them with the STORE and RESTORE commands, respectively. If you have write access, you may purge nonprivate spool files using STORE with the ;PURGE option.

Creating spool files

There are many different ways to create spool files. This section provides a quick overview of some of them.

Using a text editor

To have the spooler create a spool file, you direct output to a device whose spool queue is open. For example, when you issue the command to send a file to the printer from within a text editing program, the spooler creates an output spool file containing, among other information, the data you want to print. Try this simple example to see:

Log on to your MPE/iX system and start the text editor of your choice
Type a few lines of text and save them as MYFILE1.
Issue the command to send the text to the printer. For example, if you are using EDIT 3000, you would enter the LIST ALL, OFFLINE command at the editor prompt.
Exit the editor and, at the CI prompt, type the LISTSPF command. You'll see information something like this:

   SPOOLID    JOBNUM   FILEDES  PRI COPIES DEV      STATE  RSPFN OWNER



   #O6620     S1183    LP         8      1 LP       READY        USER.ACCOUNT



   INPUT SPOOL FILES            OUTPUT SPOOL FILES

   ACTIVE   = 0;                CREATE   = 0;              READY    = 1;

   OPEN     = 0;                DEFER    = 0;              SELECTED = 1;

   READY    = 0;                DELPND   = 0;              SPSAVE   = 0;

                                PRINT    = 0;              XFER     = 0;

                                PROBLM   = 0;



   TOTAL IN FILES   = 0;        TOTAL OUT FILES   = 1;

         IN SECTORS = 0;              OUT SECTORS = 16;



   OUTFENCE = 6

Streaming a batch job

A second way to generate a spool file is to submit a batch job that includes, as one of the list of command it executes, a command for sending a report to the printer. You use the STREAM command, followed by the name of the job file, to submit a job. For example:

   STREAM jobfile

Try these steps to create and stream a simple job that sends a few lines of text output to a printer.

Log on to your MPE/iX system and start the text editor of your choice
Type a few lines of text and save them as MYFILE1.
Using the text editor, create a job file called MYJOB1 by entering the information shown below. For the italicized words, make the appropriate substitutions. (For example, supply your user name in place of user.) If you don't have a user password, then enter the information in the form user.account/accountpass.
!JOB MYJOB1,user/userpass.account/accountpass;INPRI=9;RESTART;OUTCLASS=LP,1 !CONTINUE !EDITOR T MYFILE1 L ALL,OFFLINE EXIT !TELL user.account MYJOB1 IS DONE. !EOJ
Save this file as MYJOB1 and exit the editor.
At the CI prompt, enter the STREAM command to submit the job and note the number your job is assigned. For example:
STREAM MYJOB1
To list your output spool file, enter the LISTSPF command. For additional examples of the LISTSPF output, refer to the "LISTSPF" section in chapter 5.
Stream the same job a second time and issue another LISTSPF command to see how the listing changes.

Using the FCOPY utility

A third way to create a spool file is to copy a file to a spooled printer with the FCOPY utility. For example:

   FILE SPPRNT;DEV=LP;CCTL

   FCOPY FROM=MYFILE;TO=*SPPRNT

Using the PRINT command

A fourth way to create a spool file is to use the PRINT command with a standard MPE/iX file. For example:

   FILE SPPRNT;DEV=LP;CCTL

   PRINT MYFILE;OUT=*SPPRNT

Using the BUILD command

To create an unlinked spool file, you use the SPOOL parameter of the BUILD command. For example, to create the spool file MYSPOOL, you would enter:

   BUILD MYSPOOL;REC=-132,1,F,ASCII;DISC=3000,1,1;SPOOL

To enter data into this spool file from a file called MYFILE enter:

   FILE MYSPOOL,OLD

   PRINT MYFILE,*MYSPOOL

The ;CODE= parameter of the BUILD command accepts three file codes for spool files. The file code parameter sets a specified value in the file label, which determines the type of spool file that the BUILD command will create. Specifying one of these file code parameters without also specifying the ;SPOOL option does not make the file a spool file. You can enter one of these file codes in addition to specifying the SPOOL option.

The file codes you can enter and their corresponding mnemonic (in this case is a word-like combination of characters that is suggestive of and represents a file code) are listed below.

Integer     Mnemonic    Meaning

     INSP          input spool file

     OUTSP       output spool file

     CHKSP       output spool file checkpoint file

For example, to specify a output spool file code with the BUILD command, simply add the ;CODE= parameter as follows:

   BUILD MYSPOOL;CODE=1516

Using the FILE command

You can use the SPOOL parameter of the FILE command to create an output spool file that is not linked to the spool file directory and, therefore, will not be printed. A spool file created in this way may be printed at a later date.

To use the ;SPOOL parameter simply add it to a file equation as follows:

   FILE SPPRNT;SPOOL

The ;PRIVATE option of the FILE command also generates a spool file,but one that may be accessed in privileged mode only. Private spool files may not be saved or copied. They may only be purged, printed, or (within limits) altered using the SPOOLF command. The PURGE or COPY commands may not be used on private files. To create a private spool file, simply add ;PRIVATE onto a file equation for a spool file. For example:

   FILE SPPRNT;PRIVATE

If the file is not already a spool file, then add both the ;SPOOL and ;PRIVATE parameters to make the file a private spool file, as follows:

   FILE SPPRNT;SPOOL;PRIVATE

Using the JOB command

Another way to generate a private output spool file is to add ;PRIVATE to the JOB command. For example:

   JOB MYJOB;PRIVATE

Saving a spool file

Once the printer finishes printing your file, the output spool file is deleted. You can direct the spooler to save the output spool file to the group and account OUT.HPSPOOL instead of deleting it by adding the SPSAVE option to the JOB command at the beginning of your job file. To make these changes, do the following:

Start the text editor of your choice and text in the job file MYJOB1.
Edit the first line of MYJOB1 to change ";OUTCLASS=LP,1" to ";SPSAVE". The line should now read:
!JOB MYJOB1,user/userpass.account/accountpass;& INPRI=9;RESTART;SPSAVE
Save MYJOB2, exit the editor, and issue the STREAM command to submit the job.
When the job is complete, enter LISTSPF. Notice that the state for this job's listing is SPSAVE.

The 1 in the JOB option OUTCLASS=LP,1 specifies that the output spool file has an output priority of 1. This effectively delays the printing of the file until you raise the file's input priority to a value greater than the outfence. (The outfence determines the minimum priority a spool file must have to be eligible for printing.)

Copying a spool file

The spooler places input and output spool files in a special group and account reserved for that purpose, and not in your own group and account. Input spool files are stored in IN.HPSPOOL and output spool files are stored in OUT.HPSPOOL.

You cannot copy input spool files; they are reserved for the exclusive use of the spooler process. If you want to save an output spool file into your account, you may do so by copying this file from the group OUT.HPSPOOL with the COPY or FCOPY commands. Spool files copied in this way are unlinked from the spooling subsystem, although the original spool file in OUT.HPSPOOL remains linked.

For example, to copy the output spool file O1121 from OUT.HPSPOOL to the report file in your account, you would enter:

   COPY FROM=O1121.OUT.HPSPOOL;TO=report

You can use the COPY command to copy a spool file to a hierarchical file directory structure. You cannot use the RENAME command to move the file. Refer to MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-60115) for more information on copying files.

Changing a spool file's characteristics

You can change an output spool file's characteristics by using the SPOOLF command. For example, to change the priority of a spool file, do the following:

Issue the LISTSPF command to view your output spool files, and note the value listed in the PRI column.
Choose an output spool file from the list, note its number, and use the SPOOLF command to change the priority to 3:
SPOOLF Onnnn;ALTER;PRI=3 LISTSPF
If you get an error message, make sure that you have entered the correct output spool file number preceded by a capital O, and not a zero.
To verify that your spool file's priority is now 3, issue the LISTSPF command.

In the next series of steps, you will use the same commands to increase the number of print copies and place the file in a deferred state.

Enter LISTSPF again and notice two columns of the display: COPIES and STATE.
Choose the spool file you want to change, note its number, and enter the following command:
SPOOLF nnnn;ALTER;COPIES=3;DEFER
If you get an error message, make sure that you have entered the correct output spool file number preceded by a capital O, and not a zero.
To verify the change, issue the LISTSPF command.

Deleting a spool file

You can use the SPOOLF command to delete one or more of your output spool files before they are printed. To do so:

Enter LISTSPF and choose an output spool file to delete.
Issue the SPOOLF command with the DELETE parameter to delete the file.
SPOOLF Onnnn;DELETE
Issue the LISTSPF command once again to verify that the output spool file no longer appears on the list.