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.