$MSPL

Function

To migrate one or more spool volumes to a new spool volume or to an existing spool volume.

Syntax


>>-$MSPL--(--volser--),--+-TARGET=--volser--+---------------------------+-+-><
                         |                  +-,--DSNAME=--data_set_name-+ |   
                         |                  +-,--SPACE=--+-CYL,nnnn-+---+ |   
                         |                  |            +-TRK,nnnn-+   | |   
                         |                  |            '-MAX------'   | |   
                         |                  +-,--FORMAT-----------------+ |   
                         |                  '-,--RESERVED---------------' |   
                         '-CANCEL-----------------------------------------'

Parameters

(volser)

Specifies a comma-separated list of one or more source spool volume serial numbers.

TARGET=volser

Specifies a target spool volume serial number (volser) of 1-6 characters. If a new spool volume is specified, JES2 starts the spool for the new volume before moving the source volumes. If an existing spool volume is specified, the target volume must be in ACTIVE state. An existing target spool volume can have an existing spool data set.

DSNAME=data_set_name

Specifies a JES2 spool data set data_set_name of 1–44 characters. The DSNAME parameter can only be specified when migrating to a new spool volume. If the DSNAME parameter is not specified, the default data set name is used, which is set using the SPOOLDEF command. If the specified data set name does not exist and the SPACE parameter is also specified, JES2 creates the specified data set on the target spool volume.

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

Specifies the space allocation when moving spool volumes to a new volume. The migration requirements dictate the minimum space that is permitted. One of the following operands must be specified:

CYL,nnnn: Allocates a spool data set with nnnn number of cylinders.
TRK,nnnn: Allocates a spool data set with nnnn number of tracks.
MAX: Allocates the largest spool data set permitted by the available space on the disk and JES2 architecture limits.

FORMAT

Formats the target spool volume unconditionally before the migration starts. The FORMAT parameter is only valid when migrating to a new spool volume.

RESERVED

Leaves the target spool volume RESERVED once the migration is complete, which prohibits new allocations. The RESERVED parameter is similar to the DRAINING state, but without the associated DAS on the work queue.

CANCEL

Cancels the spool migration. Specify only the source spool volume volser; specifying other parameters returns an error message. Migration cannot be cancelled during later portions of the CATCHUP phase or any CLEANUP phases. See $D SPOOL - Display the status of spool volumes for complete information on spool migration states.

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

The $MSPL(volser,) command queues a request to move one or more existing spool volumes to a new spool volume, or to merge them with an existing spool volume. For move requests, the target spool volume specified as a volser is not recognized by JES2. When the move completes, the source spool volumes are no longer recognized by JES2.

For merge requests, the specified target must be a spool volume that is recognized by JES2. When the merge completes, the source spool volumes remain in the MAPPED state until all users of the source spool volumes have been purged.

To manage the migration of spool volume data and the access to that data, JES2 runs various operations on all members of a MAS. These operations communicate messages through JESXCF services. JESXCF services require one XCF group per active migration to identify the messages that are specific to each active migration. Because XCF groups are a limited system resource, JES2 limits the number of concurrent active migrations to five. Therefore, you must have up to five XCF groups available–one each for up to five active spool migrations. If a spool migration is requested and an XCF group is not available, JES2 refuses the request and issues a $HASP808 message with return code 57 or 58.

Note:

To determine the number of available XCF groups, run the DISPLAY XCF,COUPLE command.
The format of the XCF group name that is created is SYSMGxxx, where xxx is the source volume DASEXTNO (in printable characters). The migrator mailboxes MG$VOLSER and RN$VOLSER are created within this group for a migration, which allows JESXCF reroute to redirect messages to another member if the migrator member goes offline.
For a move migration, the source volume must be in INACTIVE state.
For conceptual information, refer to Migrating spool volumes.

Scope

Single member. The values supplied for this command will be in effect for this member only.

Related Commands

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

Context

HASCSCAN, HASPSTAB, HASPSXIT, and HASPSPOL.

Messages

$HASP003, $HASP064, $HASP423, $HASP443, $HASP630, $HASP800, $HASP807, $HASP808, $HASP809, $HASP814 and $HASP893.

The $HASP808 and $HASP809 messages display the status of a spool migration. The $HASP808 message is directed to the system log and the system console. It indicates key points in the progress of a migration, including migration initialization and completion. Any errors encountered are also sent to the system console using the $HASP808 message.

The $HASP809 message is directed to the system log only, to limit system console messages for spool migrations to key information. The $HASP809 displays the progress of the migration, including when each migration phase starts and ends. The DEBUG option VERBOSE can be used to direct $HASP809 messages to the system console in addition to the system log. This debug option sends all syslog-only messages to the system console, not just migration messages. Use the command $TDEBUG,VERBOSE=YES to turn on the debug option.

Examples

The following examples demonstrate $MSPL(volser,) command usage:

The $MSPL(volser,) command can be used to migrate one or more existing spool volumes (volsers) to a new spool volume, as shown in the following example:
1. When the following $MSPL command example is run, JES2 creates a new data set on the new spool volume J2SPL1. The default data set name is defined by the $SPOOLDEF command.
2. The data set size, specified by SPACE=MAX in the example, is the largest size possible considering the available disk space and JES2 architecture limits.
3. Once the spool volume J2SPL1 is formatted, it becomes RESERVED and remains reserved until the $TSPOOL RESERVED=NO command is executed.
4. The spool volume SPOOL6 is in the INACTIVE state prior to the migration and transitions to the MIGRATING state during the migration. SPOOL6 is removed from the SPOOL configuration (drained) at the completion of the migration.
5. The data set previously associated with the spool volume SPOOL6 can now be deleted.
6. The $HASP808 message displays the migration progress.
This example and output are shown below:
```
 1 
$MSPL(spool6),target=spool5,space=max,r

$HASP893 VOLUME(SPOOL6)
$HASP893 VOLUME(SPOOL6) STATUS=MIGRATING-MOVE,AWAITING(MIGRATION)
$HASP646 30 PERCENT SPOOL UTILIZATION
$HASP808 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=9 -- Migration INITIALIZING phase started.
$HASP423 SPOOL5 IS BEING FORMATTED
$HASP808 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume  
RC=33 -- Migration processing completed. Migration was successful.
```
The $DSPL command displays the status of the target volume:
```
$DSPL(spool5),status,percent,reserved

$HASP893 VOLUME(SPOOL5) STATUS=ACTIVE,PERCENT=0,RESERVED=YES
$HASP646 30 PERCENT SPOOL UTILIZATION                      
```

The $MSPL(volser,) command can be used to merge one or more existing spool volumes (volsers) with a single existing spool volume, as shown in the following example:

When the following $MSPL(volser,) command is run, JES2 merges spool volumes SPOOL2, SPOOL3 and SPOOL4 with the existing active spool volume SPOOL5.
Spool volume SPOOL2 is merged first, followed by SPOOL3 and then SPOOL4.
Spool volumes SPOOL3 and SPOOL4 migration phases are pending while SPOOL2 is migrating.
Once migration is complete, SPOOL2, SPOOL3 and SPOOL4 are left in the MAPPED state.
At this point, the data sets previously associated with volumes SPOOL2, SPOOL3 and SPOOL4 can be deleted.
Both spool volumes will remain in a MAPPED state until all jobs using the volumes are purged, at which point SPOOL2, SPOOL3 and SPOOL4 are removed from the SPOOL configuration (drained) and the corresponding spool extent number can be reused.

This example and output are shown below:

$MSPL(spool2,spool3,spool4),target=spool5

$HASP808 Migration of SOURCE=SPOOL2 volume to TARGET=SPOOL5 volume 
RC=9 -- Migration INITIALIZING phase started.
$HASP893 VOLUME(SPOOL2)
$HASP893 VOLUME(SPOOL2)  STATUS=MIGRATING-MERGE,AWAITING(MIGRATION)
$HASP893 VOLUME(SPOOL3)  STATUS=MIGRATING-MERGE,AWAITING(MIGRATION)
$HASP893 VOLUME(SPOOL4)
$HASP893 VOLUME(SPOOL4)  STATUS=MIGRATING-MERGE,AWAITING(MIGRATION)
$HASP646 20 PERCENT SPOOL UTILIZATION 
$HASP808 Migration of SOURCE=SPOOL2 volume to TARGET=SPOOL5 volume
RC=33 -- Migration processing completed. Migration was successful.
$HASP808 Migration of SOURCE=SPOOL3 volume to TARGET=SPOOL5 volume
RC=9 -- Migration INITIALIZING phase started.
$HASP630 VOLUME SPOOL2 INACTIVE  2 PERCENT UTILIZATION 
$HASP808 Migration of SOURCE=SPOOL3 volume to TARGET=SPOOL5 volume
RC=33 -- Migration processing completed. Migration was successful.
$HASP808 Migration of SOURCE=SPOOL4 volume to TARGET=SPOOL5 volume
RC=9 -- Migration INITIALIZING phase started.
$HASP630 VOLUME SPOOL3 INACTIVE   1 PERCENT UTILIZATION
$HASP808 Migration of SOURCE=SPOOL4 volume to TARGET=SPOOL5 volume
RC=33 -- Migration processing completed. Migration was successful.

Run the $DSPL to see the status of the target volume, and the source volumes if they are MAPPED:

$dspl
$HASP893 VOLUME(SPOOL1)  STATUS=ACTIVE,PERCENT=1
$HASP893 VOLUME(SPOOL2)  STATUS=MAPPED,PERCENT=2
$HASP893 VOLUME(SPOOL3)  STATUS=MAPPED,PERCENT=1
$HASP893 VOLUME(SPOOL4)  STATUS=MAPPED,AWAITING(JOBS),PERCENT=1
$HASP893 VOLUME(SPOOL5)  STATUS=ACTIVE,PERCENT=1
$HASP646 0.5714 PERCENT SPOOL UTILIZATION

$dspl,status,target,maptarget
$HASP893 VOLUME(SPOOL1)  STATUS=ACTIVE,MAPTARGET=NO
$HASP893 VOLUME(SPOOL2)  STATUS=MAPPED,TARGET=SPOOL5,MAPTARGET=NO
$HASP893 VOLUME(SPOOL3)  STATUS=MAPPED,TARGET=SPOOL5,MAPTARGET=NO
$HASP893 VOLUME(SPOOL4)  STATUS=MAPPED,AWAITING(JOBS),TARGET=SPOOL5,
                         MAPTARGET=NO
$HASP893 VOLUME(SPOOL5)  STATUS=ACTIVE,MAPTARGET=YES
$HASP646 30 PERCENT SPOOL UTILIZATION

The following single source to target migration displays output from the DEBUG VERBOSE option set to YES:

$tdebug,verbose=yes

$HASP827 DEBUG
$HASP827 DEBUG  BERT=YES,CKPT=YES,MISC=YES,SECURITY=YES,
$HASP827 STORAGE=YES,SYMREC=YES,VERSION=YES,VERBOSE=YES

$mspl(spool6),target=spool5

$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=4 -- Initiated drain of source volume.
$HASP893 VOLUME(SPOOL6)
$HASP893 VOLUME(SPOOL6)  STATUS=MIGRATING-MERGE,AWAITING(MIGRATION)
$HASP646 20 PERCENT SPOOL UTILIZATION
$HASP808 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=9 -- Migration INITIALIZING phase started.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=49 -- Migration phase INITIALIZING is complete. Migrator
and spool assistant subtasks have been attached.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=24 -- Migration phase SETUP-MERGE is starting.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=25 -- Migration phase SETUP-MERGE is complete.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=26 -- Migration phase COPY-MERGE is starting.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=27 -- Migration phase COPY-MERGE is complete.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=28 -- Migration phase CATCHUP-MERGE is starting.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=29 -- Migration phase CATCHUP-MERGE is complete.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=47 -- Migration phase CLEANUP-MERGE is starting.
$HASP809 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=31 -- Migration phase CLEANUP-MERGE is complete. 
$HASP808 Migration of SOURCE=SPOOL6 volume to TARGET=SPOOL5 volume
RC=33 -- Migration processing completed. Migration was successful.
$HASP806 VOLUME SPOOL6 DRAINED
$HASP850 525 TRACK GROUPS ON SPOOL1
$HASP850 150 TRACK GROUPS ON SPOOL2
$HASP850 150 TRACK GROUPS ON SPOOL3
$HASP850 150 TRACK GROUPS ON SPOOL4
$HASP850 748 TRACK GROUPS ON SPOOL5