Function

To add or reactivate a spool volume to the spool configuration.

Parameters

Cancel

JES2 cancels all jobs on the volume that can be cancelled and then deletes the volume from the configuration. If you specify CANCEL, you must also specify the P operand to allow JES2 to recover the space on other spool volumes allocated by jobs on the spool volume to be cancelled.

Drain|P

JES2 brings the new spool volume (if used with FORMAT) or the INACTIVE spool volume into the spool environment with a status of DRAINING. For an INACTIVE spool volume, this allows work to complete without permitting allocation to the spool volume.

DSNAME=data_set_name

Specifies a 1-44 character name for a JES2 spool volume data set. The DSNAME parameter can only be specified when starting a new volume. If not specified, the default data set name that is defined using the SPOOLDEF command is used.

Format

JES2 formats the new spool volume. You need to specify this parameter if you want to reformat a new spool volume that is already formatted or if you want to specify the P or Z operands for a new spool volume.

Note: If SYS1.HASPACE has ever been scratched or deleted from the volume, you should specify FORMAT.

Sysaff

JES2 associates the spool volume with the specified member(s). A member list is some combination of the following keywords separated by commas.

ANY

This volume is associated with all members in the JES2 multi-access spool configuration.

+|-memname|*

The memnames (1 to 4 characters) to be added to (+) or deleted from (-) the current list of members that this volume is associated with. If neither + nor - is specified, the affinities of the volume is explicitly set to the specified members. '*' specifies the member the command was issued on.

HALT|Z

JES2 brings the spool volume into the spool environment with a status of INACTIVE. A new volume can also be formatted but allocation of spool space is prevented.

volser

The volume serial number of the spool volume. The first 4 or 5 characters must be identical to the 4-5 character prefix specified by the VOLUME= parameter on the SPOOLDEF initialization statement. If the specified spool volume is already in use, JES2 issues the $HASP893 message indicating that it is active and allocation is permitted.

RESERVED=Yes | No

RESERVED=Yes marks the spool volume as reserved for special processing; no new allocations will be allowed. RESERVED=No clears the reserved attribute.

SPACE=(MAX|CYL,nnnn|TRK,nnnn)

Allocates a data set when starting a new spool volume. SPACE is an optional parameter. If it is not specified, no allocation will be performed.

MAX

Allocates the largest data set as possible considering the free space on disk.

CYL,nnnn

Allocates a Spool data set with nnnn cylinders.

TRK,nnnn

Allocates a Spool data set with nnnn tracks.

Note:

1. The SPACE parameter cannot be used if JES2 starts an existing Spool volume.
2. If the SPACE parameter is specified, the CANCEL or DRAIN (P) parameter cannot be specified.
3. If the SPACE parameter is specified, JES2 formats the spool volume, no matter whether or not the format parameter is specified.

Authority Required

This command requires system authority. The description of the $T RDRnn command explains how to ensure that the authority of the appropriate MVS™ system command group is assigned.

This command requires control security access authority. For a description of assigning command input authority, see z/OS JES2 Initialization and Tuning Guide, SA32-0991.

Processing Considerations

If a spool failure occurs, the operator should be instructed to issue a $Z SPL command for each volume that is in error. This will prevent JES2 from trying to allocate more space from that volume, and from being selected for work (i.e. conversion, execution, and printing).

If a member wide warm start is done without the volumes that had errors on them, then JES2 message $HASP424, VOLUME NOT MOUNTED, will be issued followed by JES2 message $HASP853, REPLY GO, QUIT, or PURGE. If the volume is thought to be recoverable at some time, reply GO. This will cause the volume to come up in an inactive state. The jobs that have space allocated from this volume will not be available for work. JES2 will not attempt to use any space from the volume until a $S SPL command is issued.

If the volume is permanently damaged, reply PURGE to this message. Reply PURGE only if you are absolutely certain that the volume cannot be recovered. Replying PURGE will cause all jobs with space allocated from that volume to be purged. No messages or warning will be issued indicating that this happened.

To lessen the impact of a spool failure, use the SPOOLDEF FENCE=(ACTIVE=YES,VOLUMES=nn)option to specify the number (nn) of volumes to initially allocate for jobs. This can be set at initialization or may be changed through an operator command. This will cause JES2 to allocate all the track groups for a job from the specified number of volumes. If spool fencing is not used, JES2 will allocate the track groups for a job from as many spool volumes as it can. Without spool fencing, the loss of one spool volume may affect more jobs in the system than if spool fencing had been used. For more information about spool fencing, see z/OS JES2 Initialization and Tuning Guide, SA32-0991.

JES2 exits 11 and 12 can be used as an alternative method for limiting the volumes from which a job may allocate space.

If the DSNAME parameter is specified with the SPACE parameter, JES2 performs a DISP=NEW allocation of the data set. If the SPACE parameter is not specified with DSNAME, JES2 performs a DISP=OLD allocation.

Scope

MAS-wide. This command has an effect across the entire MAS.

Related Commands

$D SPOOL, $S SPOOL, and $T SPOOLDEF.

Context

HASCSCAN, HASPSTAB, HASPSXIT, and HASPSPOL.

Messages

The $HASP893 message indicates the command was accepted.

The $HASP423 message indicates that an unformatted spool volume is now being formatted.

Examples

 1   $sspl(spool1),format,p

  $HASP893 VOLUME(SPOOL1)  STATUS=INACTIVE,COMMAND=(START,FORMAT,
  $HASP893                 DRAIN)
  $HASP646 2.0952 PERCENT SPOOL UTILIZATION
 

 2   $sspl(spool2),format,z

  $HASP893 VOLUME(SPOOL2)  STATUS=INACTIVE,COMMAND=(START,FORMAT,
  $HASP893                 HALT)
  $HASP646 2.0952 PERCENT SPOOL UTILIZATION

 3   $sspl(spool3)

  $HASP893 VOLUME(SPOOL3)  STATUS=DRAINING,COMMAND=(START)
  $HASP646 33.3333 PERCENT SPOOL UTILIZATION

 4   $sspl(spool4),p,cancel

  $HASP893 VOLUME(SPOOL4)  STATUS=DRAINING,COMMAND=(START,DRAIN)
  $HASP646 33.3333 PERCENT SPOOL UTILIZATION

 5   $sspl(spool5),p

  $HASP893 VOLUME(SPOOL5)  STATUS=DRAINING,COMMAND=(START,DRAIN)
  $HASP646 33.3333 PERCENT SPOOL UTILIZATION

 6   $sspl(spool6),z

  $HASP893 VOLUME(SPOOL6)  STATUS=DRAINING,COMMAND=(START,HALT)
  $HASP646 33.3333 PERCENT SPOOL UTILIZATION

 7   $sspl(spool7),space=(cyl,100)

  $HASP893 VOLUME(SPOOL7) STATUS=INACTIVE,COMMAND=(START)
  $HASP646 1.3333 PERCENT SPOOL UTILIZATION
  $HASP423 SPOOL7 IS BEING FORMATTED
  $HASP630 VOLUME SPOOL7 ACTIVE 0 PERCENT UTILIZATION

JES2 starts spool volume SPOOL7. If SPOOL7 is a new volume, a 100 cylinder sized data set is allocated. However, if SPOOL7 is already defined to JES2, the command fails and the HASP003 error message is issued.

 8   $s spool(spool7),dsname=sys1.example,space=(cyl,100) 

$HASP893 VOLUME(SPOOL7) STATUS=INACTIVE,COMMAND=(START) 
$HASP646 1.3333 PERCENT SPOOL UTILIZATION 
$HASP423 SPOOL7 IS BEING FORMATTED 
$HASP630 VOLUME SPOOL7 ACTIVE 0 PERCENT UTILIZATION

JES2 starts spool volume SPOOL7. If SPOOL7 is a new volume, a 100-cylinder data set named SYS1.example is allocated. The allocation performed is DISP=NEW. However, if SPOOL7 is already defined, the command fails and the HASP003 error message is issued.