SPOOL

Authorization

Privilege Class: G

Purpose

Use SPOOL to set control options for one or more of your virtual spool devices. The options you select modify operational functions associated with your virtual reader, printer, punch, or console. These options also control the disposition of files after they have been processed.

Operands

Reader

RDR

Printer

PRT

PUnch

PCH

CONsole

vdev

modifies the options for all of your virtual readers, printers, punches, or console spooling devices, including the starting or stopping of spooling operations. Alternatively, you can enter the virtual device number vdev of the virtual spooling device whose options you want to modify.

Options

HOld

NOHold

indicates whether you want to HOLD files.

If you specify HOLD for an output device, all the files created by the device are placed in user hold status. When a spool file is in user hold status, it is not processed at its destination device (the real printer, punch, or virtual reader) until you remove the hold status by issuing the CHANGE command with the NOHOLD option.

If you specify HOLD for an input device, files are retained after they have been read. Unless you specify the KEEP operand for the file or for the device, the file remains in the reader queue and is the next file eligible for processing. This is in contrast to the hold status on a spool file, which makes the file ineligible for processing.

A reader may not be spooled with the string CONT/RESCAN/HOLD/NOKEEP, as this would cause the same file to be processed repeatedly. If a SPOOL command is issued which would result in the reader being spooled with this combination, the reader will be spooled KEEP to remove the conflict.

Specify NOHOLD to allow files to be purged after processing.

KEep

NOKeep

indicates whether you want to retain a spool file after it has been processed. Specify KEEP if you want to retain files after they have been processed.

For a virtual printer or punch directed to a real device, after the file has been printed or punched, it is placed in user, hold status, while retaining its keep status.

For a reader, KEEP also places your spool file in user, hold status after it has been read, but keep status is not set on the file. Note that the reader DEVICE hold option does not affect file hold status.

A reader may not be spooled with the string CONT/RESCAN/HOLD/NOKEEP, as this would cause the same file to be processed repeatedly. If a SPOOL command is issued which would result in the reader being spooled with this combination, the reader will be spooled KEEP to remove the conflict.

Specify NOKEEP to reset the keep status so that files are not retained in the system after processing has been completed.

CONt

NOCont

controls the continuous spooling option.

For output devices, CONT causes all CLOSE requests to be ignored unless specified with EOF override option. NOCONT resets the option.

For readers, CONT specifies that reading will continue without end-of-file indications at the end of each virtual spool file. Reading continues until the virtual reader queue has been scanned once from beginning to end. After each spool file is read, scanning is continued at the next logical file (unless RESCAN is specified).

NOCONT specifies that end-of-file is signaled after each spool file is read. The reader resets at the next logical file.

RESCAN

NORESCAN

When a reader is spooled CONT, RESCAN causes the first logical file in the virtual reader queue to always be the next file read. This allows files which have been ordered or changed during continuous processing to become eligible for processing.

A reader may not be spooled with the string CONT/RESCAN/HOLD/NOKEEP, as this would cause the same file to be processed repeatedly. If a SPOOL command is issued which would result in the reader being spooled with this combination, the reader will be spooled KEEP to remove the conflict.

NORESCAN causes scanning to resume at the next logical file in the virtual reader queue.

EOF

NOEof

For a printer or punch, EOF causes the device to be closed automatically when 50000 records are placed into the active spool file. Punches are closed immediately at 50000 records. If page controls are found in a print file within the next 100 records, the file is closed at the end of the page. If no page controls are found by then, it is presumed there are none, and the file is closed after 50100 records.

For a reader, the EOF/NOEOF option specifies whether end-of-file is reached (as defined by the CONT/NOCONT option). EOF specifies that a unit exception is reflected on the first read past the end of the file. Further reads result in a normal read of the next file, if any, or with a unit check if the device is empty. NOEOF specifies that unit check is reflected on the first read past end-of-file, or any subsequent read to an empty reader.

CLass c

specifies the spool class of the device. The operand c is a 1-character alphanumeric field whose values can be A through Z, 0 through 9, or asterisk (*). The CLASS option determines which destination devices can process the spool file. If you print or punch a file from one of your virtual devices, the file is assigned the class that is associated with the device. The file is then printed or punched on a real device that also has this class associated with it. The operator sets this class.

The class associated with a virtual reader determines which files it recognizes for processing. If you specify a specific class, the reader processes only files of the same class. If you specify asterisk (*), the reader processes all files, regardless of class.

NOMsg

MSG

indicates whether you want to be informed about file printing and punching. If you specify MSG, you are informed of file printing and punching if the file is printed or punched on the same system as your user ID. The message is sent to you when the file begins printing or punching on a real device. Specify NOMSG if you do not want messages sent to you when the file begins printing or punching on a real device.

Copy [*] nnn

identifies the number of copies to be printed or punched when the file is spooled to the real unit record device. Note that regardless of what number you specify for COPY, only one spool file is actually created. However, z/VM® continues to associate the COPY number with the spool file until the spool file is processed by a real printer or punch. At that time, z/VM produces the specified number of real printed or punched copies. If the real printer is a 3800 device, an asterisk (*) indicates that the printer is to print each page nnn times before going on to the next page, where nnn is a decimal number from 1 to 255.

Dist distcode

Dist OFF

Dist *

specifies the distribution code to be assigned to spool files created on this virtual device. The operand distcode is one to eight characters long. You can override distcode using the DIST option on the CLOSE or CHANGE commands.

DIST OFF and DIST * reset the distribution code of the spool files to the DIST code in the system directory at the time you logged on and will not reset to an updated value until logoff.

TO userid

TO *

TO SYSTEM

sends the output of the virtual device to the virtual reader, virtual printer, or virtual punch of the specified user ID. The distribution code on the spool files retains the distribution code specified for the originator in the system directory.

When you specify the keyword TO, you retain control of the spool file. For example, you can use the TRANSFER command to retrieve the file from the specified user ID.

TO SYSTEM is equivalent to specifying OFF and resets the transferred spool option.

Reader

Printer

PUnch

identifies the spool file queue to which your file is directed. If you do not specify a queue, the file is transferred to the other user's reader queue.

CLOse

closes the spool file on the specified device regardless of the CONT setting for the device. CLOSE is equivalent to entering CLOSE with the EOF option. If PURGE is specified, CLOSE is not necessary.

PUrge

closes and purges the spool file on the specified device, regardless of the CONT setting for the device. If PURGE is specified, the CLOSE option is not necessary. PURGE is equivalent to entering CLOSE with the PURGE option.

FOR userid

FOR *

FOR SYSTEM

except for console output, the user ID option transfers the spool file from the virtual device to the corresponding virtual device of the specified user ID. z/VM transfers console output to the receiver's virtual printer. The distribution code on the spool files becomes the distribution code specified for userid in the system directory.

You can specify FOR * to change the spool file ownership and destination code to those of your own virtual machine. Specifying FOR * is equivalent to specifying the OFF operand for the device.

FOR SYSTEM is equivalent to specifying OFF and resets the transferred spool option. If you specify FOR userid, you cannot specify either the TO or the OFF operand.

OFF

resets the TO or FOR option from the previous spooling command.

FORM form

specifies the form name for the resulting spool file or files. The operand form is one to eight characters long. The FORM option determines which destination devices can process the spool file. If you print or punch a file from one of your virtual devices, the file is assigned the form associated with the device. The file is then printed or punched on a real device that also has this form associated with it. The operator sets this form.

FORM OFF

resets the form to the system default as specified by the installation.

DEST dest

specifies the destination value for the resulting spool file or files. The operand dest is a 1- to 8-character value. The DEST option determines which destination devices can process the spool file. If you print or punch a file from one of your virtual devices, the file is assigned the destination associated with the device. The file is then printed or punched on a real device that also has this destination associated with it. The operator sets this destination.

DEST ANY

indicates that the resulting spool file or files can be processed on any CP output device that meets other selection criteria, regardless of the device's DEST setting.

DEST OFF

indicates that the resulting spool files are processed by a device specifically started, or they are defaulted to OFF. OFF is the initial setting of the destination value for virtual devices.

FLash ALL

FLash nnn

signifies that a form overlay contained in the 3800 printer is to be superimposed (or flashed) onto the specified number of copies of the output. The operand name, 1- to 4-characters long, identifies the forms overlay to be used in the projection. The operand nnn must be in the range from 0 to 255. The number specifies that the first nnn copies of output are to be flashed.

For example, if you specify COPY 4 and FLASH name 2, the first two copies of your file are flashed, while the last two copies remain unflashed. If ALL is specified, the flash count matches the copy count. ALL is the default.

FLash OFF

resets the flash parameters. Blanks are inserted into the flash name field of the specified spool file or files, and the count is set to 0.

MOdify name n

assigns a copy modification module to be used when printing the spool file or files on the 3800. This function makes it possible to alter text by either preventing the printing of certain information or adding labels to output. The name must be one to four characters long.

The operand n selects one of the character sets specified by the CHARS operand, to be used for the copy modification text. The values 0, 1, 2, and 3 correspond to the order in which the table names have been specified. If no n is specified, the first character set (0) is assumed.

MOdify OFF

resets the modify parameters. Blanks are inserted into the modify name field of the spool file or files and, when printed, no modification occurs. The modify number n is set to 0.

FCB name

FCB 6

FCB 8

FCB 10

FCB 12

specifies the forms control buffer to be used when printing the spool file or files on the 3800 printer. The operand name is the 1- to 4-character name of an FCB image or the number 6, 8, 10, or 12. This number tells the 3800 to print the entire spool file at 6, 8, 10, or 12 lines per inch, regardless of the size of the paper that is currently loaded. An FCB specified at 10 will print only on a 3800 model 3 printer.

FCB OFF

resets the FCB parameter. Blanks are inserted into the FCB name field of the spool file or files and, when printed, a default FCB will control the vertical spacing of the output text.

CHars name0 name1…

CHars name0 CHars name1…

specifies the name of the character set or sets used when printing the spool file or files on the 3800 printer. Each name must be from one to four characters long, with a maximum of four names specified. The multiple use of CHARS need only be used if namen would conflict with an option name (for example, FORM) or with a user ID. If more than one name is specified, along with modification, the order in which the names appear determines which table is used for copy modification text.

CHars OFF

resets the CHARS parameters. Blanks are inserted into the name fields of character sets used for output generation. The resulting spool file or files, therefore, uses a default character set when actually printed on a 3800 printer.

LPP nnn

LPP OFF

LPP RESET

sets the lines per page value for a virtual printer or a virtual console. 'nnn' must be a decimal number with a range of 30 to 255.

If 'OFF' is specified, internal default values will be used for lines per page. The defaults are the same as those which have been used on prior releases of VM.

'RESET' will reset the lines per page value for the virtual printer or console to the global system value. This is also the default lines per page setting for virtual printers and consoles when they are defined.

The global system value for LPP may be defined in the system configuration file. If it is not defined, the default global value for the system is 'OFF'. This causes all virtual printers and consoles to be defined with a default LPP value of 'OFF'. See the z/VM: CP Planning and Administration for information about the USER_DEFAULTS Statement.

The lines per page value is used by VM functions which generate virtual printer and console output. For CP, these include console spooling, CP dump and trace output, DDR, load maps generated by HCPLDR, and SPXTAPE log files. CMS functions which use the lines per page value for virtual printer output include the PRINT, ASSEMBLE, UPDATE, GENMSG, TAPE, FILEPOOL FORMAT AUDIT, and SET DOSLNCNT commands.

The lines per page value for a virtual printer is displayed in the response for QUERY VIRTUAL PRT command (as well as other QUERY commands which display virtual printer status).

The lines per page value for a virtual console is displayed in the response for QUERY VIRTUAL CONS command (as well as other QUERY commands which display virtual console status).

The lines per page value for a virtual printer or console may be obtained by application programs by issuing DIAGNOSE X'260' subcode 08.

NAme fname ftype

NAme dsname

specifies the file name and optional file type, or the data set name that will be given to each spool file the virtual device creates. The fname and ftype values must be eight characters or fewer. The data set name may be up to 24 characters; however, if the name has more than 16 characters, it is truncated to 16 characters.

NOName

resets the NAME option. Blanks are inserted into the name field for spool files the virtual device creates.

STArt

begins placing input and output from your display station into a spool file. Full-screen data output operations are not placed in the spool file. After the console is closed, the file becomes a printer spool file. START applies only to consoles.

STOp

terminates the spooling of display station input and output. STOP does not close the console spool file. STOP applies only to consoles.

TErm

displays the display station input and output on your display screen and places it in a spool file. The TERM operand has no effect unless the START function is also in effect. TERM applies only to consoles.

NOTerm

suppresses the display of input and output on your display screen while placing it in a spool file. The display of console input and output is not suppressed if:

• It is the result of CP commands entered from CP mode
• The output line immediately precedes a virtual machine read to the console.

The NOTERM operand has no effect unless the START function is in effect. NOTERM applies only to consoles.

Full screen mode applications such as XEDIT and full screen CMS are not supported when the console is spooled NOTERM.

ASYNChronous

indicates you want to process other commands while the SPOOL command completes.

SYNChronous

prevents you from executing other commands until the SPOOL command completes.

Usage Notes

1. When specifying [TO] userid, if you omit the keyword TO, userid cannot be T or TO. If you are transferring your output to your own virtual machine, you may specify userid as an asterisk (*). If you specify TO userid, you cannot specify either the OFF or FOR operand.
2. Full screen functions may hang a user whose console is spooled NOTERM. For example, if a user is in XEDIT and tries to QUIT, the keyboard remains locked.
3. SET IMSG OFF suppresses informational messages for this command.
4. A spool file is created when the first record for a printer or punch is processed by the virtual unit record simulation routines in CP. CP associates this spool file with the virtual unit record device and assigns it a number called the spoolid (spool file identification). You can use spoolid to identify the file that you have produced, and to manipulate the file using the z/VM CP spooling commands, such as ORDER, CHANGE, and PURGE.

   When you print or punch a file, CP displays its spoolid. You can use the spoolid to find out various kinds of information about the file using the QUERY command.

5. It is important to remember that the SPOOL command controls both operational characteristics of your virtual spooling devices and the disposition of files after they have been processed.

   For example, you use the SPOOL command to select the files you want to process on your virtual readers. The SPOOL READER command does not change any of the characteristics associated with the files in your reader queue, but simply indicates whether a file is purged or retained after being read, and if it is retained, whether the file remains eligible for immediate reprocessing.

   The files in your reader queue are controlled through a combination of file characteristics and the options in effect for the virtual reader on which they are processed. Input files do not derive their characteristics from the reader, except for hold status, which is set as a function of the KEEP option. Table 1 summarizes the disposition of a reader file after it has been processed, depending on the hold/keep settings specified for the reader, and the keep setting of the file.

   For output devices (virtual printers, punches, and consoles) use the SPOOL command to define the characteristics of the spool files you are creating. You can use the SPOOL command to indicate whether files are to be held from further processing, and whether they are to be retained after they have been processed. This information is associated with the spool file itself, regardless of the characteristics of the device on which the file is to be processed. In addition, use SPOOL to direct the output files that you are creating to unit record devices (readers, printers, and punches) associated with other virtual machines.

   Table 1. Disposition of Reader Files Depending upon HOLD/KEEP Settings

   File Status	Device Options	Disposition
   NOKEEP	NOHOLD/NOKEEP	The file is purged.
   NOKEEP	NOHOLD/KEEP	The file is retained in user hold status. KEEP is not set on the file.
   NOKEEP	HOLD/NOKEEP	The file is retained and remains eligible for processing on your virtual reader.
   NOKEEP	HOLD/KEEP	The file is retained in user hold status. KEEP is not set on the file.
   KEEP	Any setting	The file is retained in user hold status. KEEP status remains on the file.

   All of your output files derive their characteristics from the virtual device on which they were created. If the output device is spooled with the KEEP and NOHOLD options, the file is printed or punched, and then placed in HOLD status, retaining its KEEP characteristics. If you change the file status to NOHOLD, the file is processed at the real device one more time and once again is placed in HOLD status. If you do not want to retain the file, you must change both its NOHOLD status and NOKEEP characteristic, or purge it using the PURGE command.

6. Unless you reset these values, the following options are the default values for your spool files:

   Device	Default Options
   Reader	NOHOLD NOKEEP NOCONT NORESCAN EOF CLASS A ¹
   Punch	NOHOLD NOKEEP NOCONT CLASS A¹ OFF COPY 001 NOMSG NONAME NOEOF DEST OFF
   Printer	NOHOLD NOKEEP NOCONT CLASS A¹ OFF COPY 001 NOMSG NONAME NOEOF DEST OFF
   Console	NOHOLD NOKEEP NOCONT CLASS T¹ OFF COPY 001 TERM TO * PRINTER NOMSG STOP NONAME NOEOF DEST OFF

   ¹These are default classes only if a specific class is not part of your entry in the system directory.

7. You can transfer a spool file to another z/VM user by issuing the SPOOL, CHANGE, CLOSE, or TRANSFER commands. Use the CHANGE and TRANSFER commands to transfer already existing files. Use the SPOOL or CLOSE commands to transfer files that you are in the process of creating, or files you plan to create. For example, if you want to transfer the printer or punch files you are creating to another user's virtual reader, enter spool vdev to userid rdr, where vdev identifies by number or type your virtual machine output device, and userid identifies the virtual machine of the receiving user. Designating a reader, a printer, or a punch is optional; the default designation is reader. The command defines the user queue to which you are directing the file.

   If you want to print or punch a file for someone else, enter spool vdev for userid, where vdev identifies by number or type your virtual machine output device, and userid identifies the virtual machine of the receiving user.

8. When a file changes ownership, as when it is changed to or from another user, the spoolid number changes also; the new number is obtained from a pool of numbers available to the file recipient.
   Thus, if user SAM transfers his file number 3 to user HARRY, he gets the response:

   RDR 0003 SENT TO HARRY RDR AS 0018

   Harry now has the file as file number 18.
9. If you specify options that apply to a 3800 printer, such as COPY(*), FLASH, MODIFY, FCB, or CHARS, the 3800 printer must be controlled by CP rather than the print server.
10. If DEST is not specified on a command that sets a DEST value, the current value is unchanged.
11. If an external security manager is installed on your system, you may not be authorized to transfer spool files using the TO and FOR options. For additional information, contact your security administrator.
12. The SPOOL command may not be used to direct files to the RDR queue of a user with a password of NOLOG. SPOOL may be used to direct files to the PRT and PUN queues of a user with a password of NOLOG.

Responses

{RDR} FILE spd1 SENT {TO  } userid {RDR } AS spd2 RECS {nnnn}
{PRT}                {FROM}        {PRT }              {nnnK}
{PUN}                              {PUN }              {nnnM}
{CON}
 
Continued:
 
COPY [*]nnn c {HOLD  } {KEEP  }
              {NOHOLD} {NOKEEP}

RDR

PRT

PUN

CON

identifies the spool file queue. If you are transferring a file to another user's virtual machine, this field indicates the queue from which the file originated. If you are receiving a file from another user, this field indicates the file queue to which the file has been added.

spd1

identifies the spool file at the time the command is issued.

TO userid

FROM

TO indicates the user to whom the file has been sent. FROM indicates the user sending the file.

RDR

PRT

PUN

identifies the spool file queue. If you are transferring a file to another user's virtual machine, this field indicates the queue to which the file has been added. If you are receiving a file from another user, this field indicates the file queue in which the file originated.

spd2

identifies the file after the command is complete.

RECS nnnn

RECS nnnK

RECS nnnM

identifies the number of logical records in the spool file. If the number is greater than 9999, the number is shown as nnnK, where K represents the number of lines rounded to the nearest 1000 records. If the number is greater than 999499, the number is shown as nnnM, where M represents the number of lines rounded to the nearest million.

COPY [*] nnn

identifies the number of copies of the file you want printed or punched when the file is produced. The asterisk (*) indicates that the 3800 printer is to copy each page nnn times before going on to the next page, where nnn is a decimal number from 1 to 255. If a file is not spooled to the 3800 printer, the function performed by specifying the asterisk (*) is ignored and duplication occurs normally.

c

identifies the spool file class assigned to the file.

HOLD

NOHOLD

identifies the user hold status associated with the file.

KEEP

NOKEEP

identifies the keep status associated with the file.

Messages

• HCP003E Invalid option - {option|command contains extra option(s) starting with option}
• HCP007E Invalid userid - userid
• HCP020E Userid missing or invalid
• HCP022E A virtual device number was not supplied or it was invalid.
• HCP026E Operand missing or invalid
• HCP030E Copies missing or invalid
• HCP035E Device type missing or invalid
• HCP040E Device {rdev|vdev|ldev} does not exist
• HCP052E Error in CP directory
• HCP053E userid|value not in CP directory
• HCP088E An invalid number was supplied for {COPY|FLASH} - operand.
• HCP418E {rdev|vdev} is not a spooled device.
• HCP422E The same option was specified twice.
• HCP423E The function requested is incompatible with a previously specified operand.
• HCP424I The requested option(s) would result in incompatible settings for reader vdev. The reader has been spooled KEEP to remove this conflict.
• HCP429E type vdev spool error; file {held|purged}
• HCP439E {User userid|*NSS|*IMG|*UCR|*NLS} spool fileid limit exceeded
• HCP475I Fatal I/O error trying to read directory from volid [for user userid]
• HCP1001E An operand is missing for option.
• HCP1013E An invalid operand was supplied for option - operand.
• HCP1551E value is an invalid number for MODIFY.
• HCP1552E More than {4|8} operands were specified for the {CHARS|CLASS} option.
• HCP1559E The DSNAME is truncated to 16 characters.