ibm:vm370-lib:cmshelp:spool.helpcmd
SPOOL
CMS Commands
- spool.helpcmd.txt
SPOOL CP Privilege Class: G Use the SPOOL command to modify the spooling control options in effect for a given virtual spooling device or for a group of devices. The SPOOL command can also start or stop the spooling of virtual console input and output. You can direct a file to a remote location by using the SPOOL command in conjunction with the TAG command. This latter function is discussed below in the section "Transmitting Files to Remote Locations." The format of the SPOOL command is: +----------+------------------------------------------------------------------+ | SPool | Reader vaddr [options1] | | | Printer PUnch vaddr [CLOSE PURGE options2] | | | CONsole vaddr [options3] | | | | | | options1: | | | [CLass c *] [CONt|NOCont] [HOld|NOHold] [EOF|NOEof] | | | options2: | | | [CLass c] [CONt|NOCont] [HOld|NOHold] [COpy nn] | | | [[OFF [To|For][userid|*|SYSTEM]] | | | options3: | | | [CLass c] [CONt|NOCont] [HOld|NOHold] [COpy nn] | | | [[OFF [To|For][userid|*|SYSTEM]] | | | [STArt|STOp] [TErm|NOTErm] [CLOSE|PURGE] | +----------+------------------------------------------------------------------+ At least one of the options must be selected; however, more than one may be specified, and they may be entered in any order on the command line. where: Reader | RDR modifies the options for all reader spool devices. Printer | PRT modifies the options for all printer spool devices. PUnch | PCH modifies the options for all punch spool devices. CONsole modifies the options for the virtual console spool file and/or initiates or stops the spooling of virtual console input and output, including CP input/output. vaddr is the virtual device address (cuu) of the virtual unit record device or console whose options are to be modified. CLass c specifies the spool class of the device. c is a one-character alphameric field whose values can be A through Z, or 0 through 9. Unless your virtual reader class is asterisk (*), you must ensure that any files to be read by your virtual reader are of the same spool class as your virtual reader. The * is the universal class; if your virtual reader is class *, it can read any file, regardless of class. CONt ignores intermediate end-of-file indications or CLOSE requests. For virtual readers, reading is continuous, with all end-of-file indicators ignored until all files spooled to the virtual machine are read in. If this option is not in effect, a unit exception is reflected to the virtual machine at the end of each spooled file. CONT specified for the punch or printer causes all CLOSE requests to be ignored until reset by NOCONT. If CONT is specified, NOCONT cannot be specified. NOCONT is the default if you do not specify CONT. CONT specifies that reading is to continue, without intervening end-of-file indications until all files in the system that belong to the user are read. If CONT is not in effect or is reset by specification of NOCONT, an end-of-file indication is reflected to the virtual machine at the end of each SPOOL file in the system. The nature of the end-of-file indication to be reflected is set by the EOF and NOEOF options. If the EOF option is in effect, end-of-file is signaled by a unit exception: this corresponds to pressing the end-of-file button on a real card reader. If NOEOF is in effect for a virtual reader, end-of-file is signaled by the reflection of a unit check/intervention required status. NOCont resets the continuous spooling option. If NOCONT is specified, CONT cannot be specified. NOCONT is the default if CONT is not specified. HOld places all files created by the specified device in a user hold status. For READER files, this option specifies that input files for the specified reader are not deleted from the system after they are read. The status of all files must be changed by the CHANGE command. The status of output devices is changed by the SPOOL command. If HOLD is specified, NOHOLD cannot be specified. If the HOLD option is specified for a virtual printer or punch that is transferred to a user for input (TO userid), that virtual device places a user hold status on the reader file. The user receiving the file cannot read its status until it is changed by issuing the CHANGE command with the NOHOLD operand. The spool file class of the virtual output device must match the class of the receiver's virtual reader (or the virtual reader must have a class of *) in order for the spool file to be processed. If these conditions are not satisfied, the reader appears empty to the virtual machine attempting to read a file, even though reader files do exist. If a virtual reader is operating with CONT and HOLD, the input files for the specified reader are not deleted after they are used, but placed in a user HOLD status. The file cannot be read until it is changed (using the CHANGE command) to a NOHOLD status. NOHold resets the HOLD operand. Future files are not held. NOHOLD resets the HOLD operand in effect for the specified reader. This operand can be overridden for an active file being closed by the CLOSE command using the HOLD or NOHOLD operand. If NOHOLD is specified, HOLD may not be specified. EOF sets a virtual end-of-file condition on the specified reader, thereby ensuring that a unit exception condition is reflected on the read that follows the reading of the last card in a file. If EOF is specified, NOEOF may not be specified. NOEof specifies that the reading continues to physical end-of-file. The virtual reader stops when no cards are left in the reader and when a unit check/intervention required status is pending. If NOEOF is specified, EOF may not be specified. [To] userid | * | SYSTEM transfers the output of the virtual device to the virtual card reader of the specified userid. If TO is omitted, the userid may not be "TO" or "T." TO * may be coded if the output is to be transferred to your own virtual card reader. If TO userid is specified, neither OFF nor FOR may be specified on the same command line. If you specify COPY with TO userid, the number of copies you specify has no effect on the receiver of the spool file; he receives only one copy. However, if OFF or FOR is specified on a subsequent command, the receiver of your spool file receives the number of copies you specify via COPY. For example, if the following command is entered: SPOOL PUN TO USERA COPY 3 CLASS B the COPY operand has no effect on the file going to USERA. However, if the command: SPOOL PUN OFF -- or -- SPOOL PUN FOR USERA is entered, the COPY 3 specified in the first statement affects subsequent punch files. TO SYSTEM is equivalent to specifying OFF and resets the transferred spool option. For userid | * | SYSTEM indicates the userid under which printed or punched output is produced. The userid becomes the owner of the output spool file and the distcode on the file is the distcode for the user that is specified in the VM/370 directory. The file is not transferred to the user's reader input. The default setting is for your own virtual machine identification. FOR *, or FOR SYSTEM can be coded to specify your own identification and is equivalent to the OFF option. OFF resets the transferred spool option. COpy nn is the number of copies that are to be printed or punched when the file is spooled to the real unit record device. This operand is valid only for output files; the number of copies, nn must be between 1 and 99 (leading zeros need not be specified). CLOSE closes the specified device regardless of the CONT setting for the device. If CLOSE is specified, PURGE may not be specified. CLOSE does not affect the setting of any other operand and is provided as a convenience to close a virtual output device. As an example, this sequence of commands: SPOOL PRT CONT (print file) (print file) SPOOL PRT NOCONT CLOSE PRT SPOOL PRT CONT (print file) can be replaced with the following sequence to achieve the desired result: SPOOL PRT CONT (print file) (print file) SPOOL PRT CLOSE (print file) PURGE closes and purges the spool file from the specified virtual output device regardless of the CONT setting for the device. If PURGE is specified, CLOSE cannot be specified. PURGE does not affect the setting of any other operand and is equivalent to issuing the CLOSE command for a device (or type of device) with the PURGE operand. STArt places all console input and output in a spool file. Until a CLOSE is issued for the console, characteristics of the console spool file may be changed by use of the SPOOL CONSOLE command. After the console is closed, the file becomes a printer spool file whose characteristics can be changed by issuing the CHANGE PRINTER command. STop terminates the spooling of console input and output. The command SPOOL CONSOLE STOP does not close the console spool file. TErm displays the virtual console input and output at the terminal in addition to placing it in a spool file. The TERM operand has no effect until the START operand is specified. NOTErm suppresses the display of console input and output of a system running in a virtual machine. The display of console input and output is not suppressed if: o It is the result of CP commands entered from CP mode. o It is a message or warning. o It is the result of a CP command entered by means of the #CP command. o It is the result of Commands entered on a 3270 in CMS EDIT mode. o The output line immediately precedes a virtual machine read to the console. (This output line prints twice in the spooled console file.) The NOTERM operand has no effect until the START operand is specified. Usage notes: Unless otherwise set, the following options are default values for spool files: Reader NOHOLD NOCONT CLASS * EOF Punch NOHOLD NOCONT CLASS A OFF COPY 001 Printer NOHOLD NOCONT CLASS A OFF COPY 001 FLASHC 000 Console NOHOLD NOCONT CLASS T OFF COPY 001 TERM The above are the default classes only if a specific class option is not part of the VM/370 directory entry. Spool Class Considerations Your system programmer can define certain spool classes to automatically print certain classification titles (for, example, SECRET, TOP SECRET or TIPPY TOP SECRET). The title prints on the separator page, and, optionally, at the bottom of each printed page. Ask your system programmer if he has defined certain classes for this function, or request that classes be defined. For example, you may wish class S to print SECRET on the separator page, and class X to print TIPPY TOP SECRET on the separator page and also on the bottom of each page of output. The Spoolid Number: An Identifier for Your Spool Files Once you close a spool file by issuing the CMS PRINT or PUNCH command or the CP CLOSE command, CP assigns the spool file a number between 1 and 9900. This number is called the spoolid (spool file identification) for the file. It can be used as a convenient way to identify the file. It can also be used when you are manipulating the file with VM/370 spooling commands such as ORDER, CHANGE or CLOSE. Spoolids are assigned to all your spool files sequentially. When the maximum number (9900) is assigned, CP begins again with the number 1. When you print or punch a file, CP displays at your terminal the spoolid it assigned to your file if (1) multiple copies of the file are being processed, (2) the file is being transferred to another user, or (3) the file is placed in a user hold status. You can find out various kinds of information about a file using the spoolid with the many forms of the QUERY command. Transmitting Spool Files Locally Spool files can be transferred between users via the SPOOL and TRANSFER commands. To transfer printer or punch files of your virtual machine to the virtual reader of some other user, issue the SPOOL command with the TO option: SPOOL device TO userid where device is the virtual device type or virtual address (for example, PRINTER, PUNCH, 00E) and userid is the name of the designated user's reader. If you only want to print or punch a file for someone else, you can issue the SPOOL command with the FOR option: SPOOL device FOR userid where device is the same as the previous example. The userid provides the distribution code for the designated user. To transfer printer or punch files from your virtual card reader to another user's reader, issue the TRANSFER command with the TO option: TRANSFER option TO userid where option is SPOOLID, CLASS, or ALL and userid is the designated user's virtual reader. If you merely wish to reclaim a transferred file, you can issue the same command with the FROM option: TRANSFER option FROM userid where option and userid are the same as the previous example. Notes: 1. Files that have been spooled for another user are not in that user's virtual reader and, therefore, you cannot reclaim them. 2. You can transfer any file that is queued on your virtual readers; however, you can reclaim only those files which you originated. Transmitting Files to Remote Locations To direct files to remote stations, use the CP TAG and SPOOL commands in conjunction with a command that causes the file to be closed and sent to a virtual device (for example, a virtual printer or punch). Use the TAG command to specify the device to be spooled and to associate with that device the location identifier (locid) for the destination of the file: TAG DEV device locid where device is the virtual device type (for example, PRINTER or PUNCH) or virtual device address (vaddr) and locid is the name of the destination to which the file is to be transmitted. Use the SPOOL command to specify that output to the device specified in the command is to be sent to the RSCS virtual machine, which performs the actual transmission of the file: SPOOL device TO userid where device is the same virtual device type or virtual device address specified in the TAG command and userid is the userid of the RSCS virtual machine at your installation. You can find out the userid of your installation's RSCS virtual machine and the locid for the various remote stations from your installations' system programmer. After you issue the TAG and SPOOL commands, use a command (such as the CMS PRINT or PUNCH command or the CP CLOSE command) to cause the spool file to be generated, closed, and spooled to the specified virtual device. Once you have closed a spool file that is spooled to another user, you cannot change or query the spool file tag. If the file has not been selected for processing by the RSCS virtual machine, you can use the TRANSFER command to get the file back to your virtual reader. When changes are necessary, you can issue the TAG QUERY DEV or FILE command to determine the TAG information associated with a given virtual device or spool file. You can then use the FILE operand of the TAG command to change a tag that was previously set. The following example shows how to use these three commands to transmit a CMS file to a remote location: TAG DEV PUNCH CAMBRIDG SPOOL PUNCH TO NET PUNCH MYPROG ASSEMBLE The TAG command defines the type of file to be transmitted, a punch file, and the remote station to which you want it transmitted, CAMBRIDG. NET is the userid of the virtual machine controlling the RSCS network: you direct your file to that virtual machine with the SPOOL command. The PUNCH command causes the file MYPROG ASSEMBLE to be punched on your virtual machine card punch, closed, and then spooled to the virtual reader of the RSCS virtual machine, which you specified in the SPOOL command. The RSCS virtual machine then processes your file (now a VM/370 spool file) and transmits it across the RSCS network. Receiving Files from a Remote Spooling Network If your virtual machine is logged on VM/370, the remote spooling network notifies you of the arrival of a file for your machine from the RSCS network by displaying a message at your terminal. The file is sent to your virtual card reader. VM/370 can accumulate files from the network destined for your virtual card reader, regardless of whether you are logged on your virtual machine or not. If you are logged on your virtual machine, issue the QUERY command to see if you have any files in your virtual reader. When you log on your virtual machine, the logon process transmits a message informing you of accumulated spool files residing in your virtual reader (punch or printer). Spooling Considerations During Shutdown and Abend Situations CP does not automatically close user console spool files when VM/370 abends or the operator issues the SHUTDOWN command. The abend or SHUTDOWN condition causes console records to be lost and, consequently, an incorrect record count for spool files. Response: If the SPOOL command is used to close an output device, the informational message PRT¦PUN¦CON FILE spoolid TO¦FOR userid COPY nn HOLD¦NOHOLD is received if (1) multiple copies of the file are being processed, (2) the file is being transferred to another user, or (3) the file is placed in a user hold status. However, if SET IMSG OFF is in effect, this message is not issued, even though the above conditions are met.
ibm/vm370-lib/cmshelp/spool.helpcmd.txt · Last modified: 2023/08/06 13:36 by Site Administrator