Host Console operations
This chapter provides information about how to operate the IBM TS7700, with an emphasis on commands and procedures that work with the z/OS host operating system.
This chapter includes the following sections:
10.1 System-managed tape
This section describes the commands that are used to operate a tape library in an IBM z/OS and system-managed tape environment. It is not intended to replace the full operational procedures in the product documentation. It is a quick reference for some of the more useful DFSMS and MVS commands.
10.1.1 DFSMS operator commands
Some of the commands contain libname as a variable. In this case, the storage management subsystem (SMS)-defined library name is required. The output for some of these commands differs slightly depending on whether you reference a TS7700 composite library or distributed library. For more information about DFSMS commands, see z/OS DFSMS Object Access Method Planning, Installation, and Storage Administration Guide for Tape Libraries, SC23-6867.
Information from the IBM TS4500/TS3500 Tape Library is contained in some of the outputs. However, you cannot switch the operational mode of the TS4500/TS3500 Tape Library with z/OS commands.
|
Consideration: DFSMS and MVS commands apply only to SMS-defined libraries. The library name that is defined during the definition of a library in Interactive Storage Management Facility (ISMF) is required for libname in the DFSMS commands. The activation of a source control data set (SCDS) with this libname must have already been performed for SMS to recognize the library.
|
The following DFSMS operator commands support the tape library:
•DISPLAY SMS,LIBRARY(libname|ALL),STATUS
This is an SMS Configuration level view, which indicates whether the SMS-defined libraries are online, offline, or pending offline, on each of the systems in the configuration.
STATUS is the default parameter.
•DISPLAY SMS,LIBRARY(ALL),DETAIL
The DETAIL display, although a single-system view, gives much more information. This is the suggested method to display a high-level overview of each library that is defined to SMS in the configuration. See Example 10-1.
Example 10-1 D SMS,LIB(ALL),DETAIL
D SMS,LIB(ALL),DETAIL
CBR1110I OAM library status: 738
TAPE LIB DEVICE TOT ONL AVL TOTAL EMPTY SCRTCH ON OP
LIBRARY TYP TYPE DRV DRV DRV SLOTS SLOTS VOLS
CLIB00 VCL GRID 512 0 0 0 0 0 N Y
DTS7720 VDL 3957-VEB 0 0 0 559 516 0 Y Y
D0001 VDL 3957-V07 0 0 0 1000 960 0 Y N
D0002 VDL 3957-V07 0 0 0 1000 880 0 Y N
E0001 VDL 3957-V07 0 0 0 1000 883 0 Y N
E0002 VDL 3957-V07 0 0 0 1000 880 0 Y N
HYDRAE VDL 3957-V07 0 0 0 185 129 0 Y Y
HYDRAG VCL GRID 512 2 2 0 0 45547 Y Y
•DISPLAY SMS,LIBRARY(libname),DETAIL
This command provides details about the status of a single library. It is the only command that displays the library state (auto, pause, or manual mode). The status lines at the bottom of the output are surfaced based on information that is obtained directly from the library. See Example 10-2.
Example 10-2 D SMS,LIB(libname),DETAIL
D SMS,LIB(HYDRAG),DETAIL
CBR1110I OAM library status: 754
TAPE LIB DEVICE TOT ONL AVL TOTAL EMPTY SCRTCH ON OP
LIBRARY TYP TYPE DRV DRV DRV SLOTS SLOTS VOLS
HYDRAG VCL GRID 512 2 2 0 0 45547 Y Y
----------------------------------------------------------------------
MEDIA SCRATCH SCRATCH SCRATCH
TYPE COUNT THRESHOLD CATEGORY
MEDIA1 10 0 0021
MEDIA2 45537 0 0022
----------------------------------------------------------------------
DISTRIBUTED LIBRARIES: HYDRAE DTS7720
----------------------------------------------------------------------
LIBRARY ID: 00186
OPERATIONAL STATE: AUTOMATED
ERROR CATEGORY SCRATCH COUNT: 1
CORRUPTED TOKEN VOLUME COUNT: 24
----------------------------------------------------------------------
Library supports import/export.
Library supports outboard policy management.
Library supports logical WORM.
Library enabled for scratch allocation assistance.
•DISPLAY SMS,VOLUME(volser)
This command displays all of the information that is stored about a volume in the tape configuration database (TCDB), also known as the VOLCAT, as well as information obtained directly from the library, such as the LIBRARY CATEGORY, LM constructs (SMS constructs stored in the library), and LM CATEGORY. See Example 10-3.
Example 10-3 D SMS,VOLUME(volser)
D SMS,VOL(B00941)
RESPONSE=MZPEVS2
CBR1180I OAM tape volume status: 195
VOLUME MEDIA STORAGE LIBRARY USE W C SOFTWARE LIBRARY
TYPE GROUP NAME ATR P P ERR STAT CATEGORY
B00941 MEDIA2 SGG00001 HYDRAG P N N NOERROR PRIVATE
-------------------------------------------------------------------
RECORDING TECH: 36 TRACK COMPACTION: YES
SPECIAL ATTRIBUTE: NONE ENTER/EJECT DATE: 2011-02-14
CREATION DATE: 2011-02-14 EXPIRATION DATE: 2014-11-15
LAST MOUNTED DATE: 2014-11-10 LAST WRITTEN DATE: 2014-11-10
SHELF LOCATION:
OWNER: DENEKA
LM SG: SGG00001 LM SC: SC00030R LM MC: MNDNN020 LM DC: D000N004
LM CATEGORY: 002F
•DISPLAY SMS,OAM
This command, which is shown in Example 10-4, is primarily useful for checking the status of the object access method (OAM) user exits and, if the CBROAMxx parmlib member was used during OAM startup, the suffix of this member.
Example 10-4 D SMS,OAM
D SMS,OAM
RESPONSE=MZPEVS2
CBR1100I OAM status: 744
TAPE TOT ONL TOT TOT TOT TOT TOT ONL AVL TOTAL
LIB LIB AL VL VCL ML DRV DRV DRV SCRTCH
3 1 0 0 3 0 1280 2 2 45547
There are also 7 VTS distributed libraries defined.
CBRUXCUA processing ENABLED.
CBRUXEJC processing ENABLED.
CBRUXENT processing ENABLED.
CBRUXVNL processing ENABLED.
CBROAM: 00
•VARY SMS,LIBRARY(libname),ONLINE/OFFLINE
From the host standpoint, the vary online and vary offline commands for a TS7700 library always use the library name as defined through ISMF.
This command acts on the SMS library, which is referred to as libname. Using this command with the OFFLINE parameter stops tape library actions and gradually makes all of the tape units within this virtual library unavailable. This simple form is a single-system form. The status of the library remains unaffected in other MVS systems.
|
Note: A composite and distributed IBM Virtual Tape Server (VTS) library can be varied online and offline like any VTS library, though varying a distributed library offline from the host really has no meaning (does not prevent outboard usage of the library). Message CBR3016I warns the user when a distributed library is offline during OAM initialization or is varied offline while OAM is active.
|
Using this command with the ONLINE parameter is required to bring the SMS-defined library back to operation after it has been offline.
•VARY SMS,LIBRARY(libname,sysname,...),ON/OFF and VARY SMS,LIBRARY(libname,ALL),ON/OFF
This extended form of the VARY command can affect more than one system. The first form affects one or more named MVS systems. The second form runs the VARY action on all systems within the SMSplex.
The VARY SMS command enables the short forms ON as an abbreviation for ONLINE and OFF as an abbreviation for OFFLINE.
•LIBRARY EJECT,volser,{PURGE|KEEP|LOCATION}
When issued against a virtual volume in a TS7700, the EJECT command is used to delete that virtual volume from the TS7700. The following options are available for this command:
– Delete from the TS7700 virtual volumes that are considered scratch. This command cannot be used to eject a physical backend volume from a TS3500 or TS4500 because the host has no knowledge of backend tape libraries.
– Remove the volume record from the TCDB (PURGE or P).
– Keep the volume record in the TCDB and update it to indicate that the cartridge has been ejected (KEEP or K). If the record contains information in the SHELF location field, it is not changed. If the SHELF location field is empty, the operator must enter information about the new location as a reply to write to operator with reply (WTOR). The reply can be up to 32 characters long.
– Keep the volume record in the TCDB and update it, including updating the SHELF location even if there is information in this field (LOCATION or L). The operator must enter the new information as a reply to WTOR.
If none of the variations (PURGE, KEEP, or LOCATION) is indicated in the command, a default decides whether the record is kept or purged. This default can be set separately for each library through the ISMF Library Definition window.
This command is available for the operator to delete a single virtual volume. Mass deletion of virtual volumes is performed through program interfaces, such as ISMF, a tape management system (TMS), or a batch job.
10.1.2 MVS system commands
The following commands are described in detail in z/OS MVS System Commands, SA22-7627:
•VARY unit,ONLINE/OFFLINE
The VARY unit command is no different from what it was before. However, new situations are seen when the affected unit is attached to a library.
When the library is offline, the tape units cannot be used. This is internally indicated in a new status (offline for library reasons), which is separate from the normal unit offline status. A unit can be offline for both library and single-unit reasons.
A unit that is offline only for library reasons cannot be varied online by running VARY unit,ONLINE. Only VARY SMS,LIBRARY(...),ONLINE can do so.
You can bring a unit online that was individually varied offline, and was offline for library reasons, by varying it online individually and varying its library online. The order of these activities is not important, but both are necessary.
•LIBRARY DISPDRV,library_name
The LIBRARY DISPDRV (LI DD) command indicates whether a device is online or offline, and the reason if it is offline. With OAM APAR OA47487 and Release 3.3 installed, a new keyword MOUNTED is added to this command. This keyword specifies that status information should be displayed for volumes that are mounted in the TS7700 for the specified library (composite or distributed). Information pertaining to the distributed library that owns the device for the mount, and distributed library information that is associated with the primary and the secondary Tape Volume Cache (TVC), is displayed.
There is an ALL parameter that can be passed with MOUNTED. ALL specifies that additional drives can be displayed that are not owned by the distributed library that is targeted in the command. The additional drives are displayed if the distributed library that is specified is the primary or secondary TVC for the mounted volume.
As with the existing LIBRARY DISPDRV command, the host must be able to communicate with the device and the device can be online or offline. Unlike the existing LIBRARY DISPDRV command, the OAM address space must have been started on the host, but does not have to be currently active.
The intent of the addition of MOUNTED to the LI DD command is to provide a way to tell which devices and volumes are mounted where in the grid without having to query individual volumes. This parameter should aid in the process of placing a cluster into service mode by simplifying the process of identifying which devices must be varied offline.
Here is the syntax for the LIBRARY DISPDRV MOUNTED,ALL command:
LIBRARY DISPDRV,library_name,MOUNTED and
LIBRARY DISPDRV,library_name,MOUNTED,ALL
or
LI DD,library_name,M
LI DD,library-name,M,A
library_name can be a composite or distributed library. The following examples illustrate the differences in the display output. Here is the configuration for the clusters in the example COMPLIB1 grid:
– DISTLIB1 – (1C00 – 1CFF): Devices 1C05, 1C10, 1C25, 1C30, 1C45, and 1C48 are mounted. The mounts are satisfied by the primary TVC being DISTLIB1. Synchronous mode copy is not used for allocations that are directed to this cluster.
– DISTLIB2 – (1D00 - 1DFF): Devices 1D03, 1D1C, 1D22, 1D35, and 1D42 are mounted. The primary TVC is DISTLIB1 for some of the volumes and DISTLIB2 for others. The mounted volumes are in synchronous mode and copied to DISTLIB3.
– DISTLIB3 – (1E00 - 1EFF): Devices 1E1F, 1E21, 1E30, 1E56, and 1E68 are mounted. The primary TVC is a combination of all three clusters. Synchronous mode copy is not used for allocations that are directed to this cluster.
In Example 10-5, all volumes that are mounted in the grid are displayed along with the distributed library in which they are mounted.
Example 10-5 LIBRARY DISPDRV MOUNTED command against a composite library
LIBRARY DISPDRV,COMPLIB1,MOUNTED
CBR1230I Mounted status:
DRIVE COMPLIB ON MOUNT DISTLIB PRI-TVC SEC-TVC
NUM NAME VOLUME Name DISTLIB DISTLIB
1C05 COMPLIB1 Y A00100 DISTLIB1 DISTLIB1
1C10 COMPLIB1 Y A00108 DISTLIB1 DISTLIB1
1C25 COMPLIB1 Y A00115 DISTLIB1 DISTLIB1
1C30 COMPLIB1 Y A00050 DISTLIB1 DISTLIB1
1C45 COMPLIB1 Y A00142 DISTLIB1 DISTLIB1
1C48 COMPLIB1 Y A01001 DISTLIB1 DISTLIB1
1D03 COMPLIB1 Y A00118 DISTLIB2 DISTLIB1 DISTLIB3
1D1C COMPLIB1 Y A00124 DISTLIB2 DISTLIB2 DISTLIB3
1D22 COMPLIB1 Y A00999 DISTLIB2 DISTLIB1 DISTLIB3
1D35 COMPLIB1 Y A00008 DISTLIB2 DISTLIB2 DISTLIB3
1D42 COMPLIB1 Y A00175 DISTLIB2 DISTLIB1 DISTLIB3
1E1F COMPLIB1 Y A00117 DISTLIB3 DISTLIB3
1E21 COMPLIB1 Y A02075 DISTLIB3 DISTLIB1
1E30 COMPLIB1 Y A01070 DISTLIB3 DISTLIB1
1E56 COMPLIB1 Y A00004 DISTLIB3 DISTLIB2
1E68 COMPLIB1 Y A00576 DISTLIB3 DISTLIB3
In Example 10-6, the command is directed to a specific distributed library in the grid. You see the mounts for devices only in that specific distributed library.
Example 10-6 LIBRARY DISPDRV MOUNTED command against a distributed library
LIBRARY DISPDRV,DISTLIB3,MOUNTED
CBR1230I Mounted status:
DRIVE COMPLIB ON MOUNT DISTLIB PRI-TVC SEC-TVC
NUM NAME VOLUME Name DISTLIB DISTLIB
1E1F COMPLIB1 Y A00117 DISTLIB3 DISTLIB3
1E21 COMPLIB1 Y A02075 DISTLIB3 DISTLIB1
1E30 COMPLIB1 Y A01070 DISTLIB3 DISTLIB1
1E56 COMPLIB1 Y A00004 DISTLIB3 DISTLIB2
1E68 COMPLIB1 Y A00576 DISTLIB3 DISTLIB3
In Example 10-7, the ALL keyword has been added to the command. It now includes all mounts where the DISTLIB, PRI-TVC, or SEC-TVC is the distributed library that is specified on the command.
Example 10-7 LIBRARY DISPDRV MOUNTED ALL command against a distributed library
LIBRARY DISPDRV,DISTLIB3,MOUNTED,ALL
CBR1230I Mounted status:
DRIVE COMPLIB ON MOUNT DISTLIB PRI-TVC SEC-TVC
NUM NAME VOLUME Name DISTLIB DISTLIB
1D03 COMPLIB1 Y A00118 DISTLIB2 DISTLIB1 DISTLIB3
1D1C COMPLIB1 Y A00124 DISTLIB2 DISTLIB2 DISTLIB3
1D22 COMPLIB1 Y A00999 DISTLIB2 DISTLIB2 DISTLIB3
1D35 COMPLIB1 Y A00008 DISTLIB2 DISTLIB2 DISTLIB3
1D42 COMPLIB1 Y A00075 DISTLIB2 DISTLIB1 DISTLIB3
1E1F COMPLIB1 Y A00117 DISTLIB3 DISTLIB3
1E21 COMPLIB1 Y A02075 DISTLIB3 DISTLIB1
1E30 COMPLIB1 Y A01070 DISTLIB3 DISTLIB1
1E56 COMPLIB1 Y A00004 DISTLIB3 DISTLIB2
1E68 COMPLIB1 Y A00576 DISTLIB3 DISTLIB3
For a complete description of this command and its output, see APAR OA47487.
•DISPLAY M=DEV(xxxx)
The D M=DEV command is useful for checking the operational status of the paths to the device. See Example 10-8.
Example 10-8 D M=DEV
D M=DEV(2500)
IEE174I 04.29.15 DISPLAY M 626
DEVICE 02500 STATUS=OFFLINE
CHP B2 B3 B8 B9
ENTRY LINK ADDRESS 20 21 22 23
DEST LINK ADDRESS D4 D5 D6 D7
PATH ONLINE Y Y N N
CHP PHYSICALLY ONLINE Y Y Y Y
PATH OPERATIONAL Y Y Y Y
MANAGED N N N N
CU NUMBER 2500 2500 2500 2500
MAXIMUM MANAGED CHPID(S) ALLOWED: 0
DESTINATION CU LOGICAL ADDRESS = 00
SCP CU ND = NOT AVAILABLE
SCP TOKEN NED = 003490.C2A.IBM.78.0000000H6395.0000
SCP DEVICE NED = 003490.C2A.IBM.78.0000000H6395.0000
•DISPLAY U
The DISPLAY U command displays the status of the requested unit. If the unit is part of a tape library (either manual or automated), device type 348X is replaced by 348L. An IBM 3490E is shown as 349L, and a 3590 or 3592 is shown as 359L.
•MOUNT devnum, VOL=(NL/SL/AL,serial)
The processing of MOUNT has been modified to accommodate automated tape libraries and the requirement to verify that the correct volume has been mounted and is in private status in the TCDB.
•UNLOAD devnum
The UNLOAD command enables you to unload a drive, if the Rewind Unload (RUN) process was not successful initially.
10.1.3 Host Console Request function
The LIBRARY REQUEST host console command (LI REQ) provides a simple way for an operator to determine the status of the TS7700 to obtain information about the resources of the TS7700, or to run an operation in the TS7700. It can also be used with automation software to obtain and analyze operational information that can then be used to alert a storage administrator that something must be examined further.
With the 3.2 code release, the TS7700 Management Interface (MI) enables an operator to issue a Library Request host console command as through it was issued from the z/OS host. The result of the command is displayed on the MI window.
The command accepts the following parameters:
•A library name, which can be a composite or a distributed library.
•It also enables 1 - 4 keywords, with each keyword being a maximum of 8 characters.
The specified keywords are passed to the TS7700 identified by the library name to instruct it about what type of information is being requested or which operation is to be run. Based on the operation that is requested through the command, the TS7700 then returns information to the host that is displayed in multiline write to operator (WTO) message CBR1280I.
|
Note: The information that is presented in the CBR1280I message comes directly from the hardware as a response to the LI REQ command. If you have a question about the information that is presented to the host in the CBR1280I messages that is generated as a response to an LI REQ command, engage IBM hardware support.
|
This section describes some of the more useful and common LI REQ commands that a client uses. A detailed description of the Host Console Request functions and responses is available in IBM TS7700 Series z/OS Host Command Line Request User’s Guide, which is available at the Techdocs website:
Command syntax for the Host Console Request function
The Host Console Request is also referred to as the LIBRARY REQUEST command. The syntax of the command is shown in Example 10-9.
Example 10-9 Host Console Request function syntax
>>__ _LIBRARY_ ___REQUEST___,__library_name________________________>
|_LI______| |_REQ_____|
>___ _,keyword1___________________________________________________><
|_,keyword2____________________| |_,L=_ _a______ __|
|_,keyword3____________________| |_name___|
|_,keyword4____________________| |_name-a_|
The following parameters are required:
REQUEST | REQ Specifies a request to obtain information from the TS7700, or to run an outboard operation.
library_name Specifies the library name that is associated with the TS7700 to which the request needs to be directed. The library name that is specified can be a composite or a distributed library, and which library is applicable depends on the other keywords specified.
keyword1 Specifies which operation is to be run on the TS7700.
The following parameters are optional. The optional parameters depend on the first keyword specified. Based on the first keyword that is specified, zero or more of the additional keywords might be appropriate:
keyword2 Specifies additional information in support of the operation that is specified with the first keyword.
keyword3 Specifies additional information in support of the operation that is specified with the first keyword.
keyword4 Specifies additional information in support of the operation that is specified with the first keyword.
L={a | name | name-a}
Specifies where to display the results of the inquiry: the display area (L=a), the console name (L=name), or both the console name and the display area (L=name-a). The name parameter can be an alphanumeric character string.
Specifies where to display the results of the inquiry: the display area (L=a), the console name (L=name), or both the console name and the display area (L=name-a). The name parameter can be an alphanumeric character string.
Note the following information:
•If the request is specific to the composite library, the composite library name must be specified.
•If the request is specific to a distributed library, the distributed library name must be used.
•If a request for a distributed library is received on a virtual drive address on a TS7700 cluster of a separate distributed library, the request is routed to the appropriate cluster for handling, and the response is routed back through the requesting device address.
LIBRARY REQUEST,composite_library,STATUS,GRID
In addition to surfacing other information about the status of a grid, this command is an easy way to determine what microcode level exists for each cluster in a grid. Sample output for this command is shown in Example 10-10.
Example 10-10 LIBRARY REQUEST,libname,STATUS,GRID
LIBRARY REQUEST,ATL3484F,STATUS,GRID
CBR1020I Processing LIBRARY command: REQUEST,ATL3484F,STATUS,GRID.
IEF196I IEF237I 0801 ALLOCATED TO SYS00093
CBR1280I Library ATL3484F request. 467
Keywords: STATUS,GRID
----------------------------------------------------------------------
GRID STATUS V2 .0
COMPOSITE LIBRARY VIEW
IMMED-DEFERRED OWNERSHIP-T/O RECONCILE HCOPY
LIBRARY STATE NUM MB MODE NUM NUM ENB
cluster0 ON 0 0 - 0 0 Y
cluster1 ON 0 0 - 0 0 Y
cluster2 ON 0 0 - 0 0 Y
----------------------------------------------------------------------
COMPOSITE LIBRARY VIEW
SYNC-DEFERRED
LIBRARY NUM MB
cluster0 0 0
cluster1 0 0
cluster2 0 0
----------------------------------------------------------------------
DISTRIBUTED LIBRARY VIEW
RUN-COPY-QUEUE DEF-COPY-QUEUE LSTATE PT FAM
LIBRARY STATE NUM MB NUM MB
cluster0 ON 0 0 0 0 A Y -
cluster1 ON 0 0 0 0 A N -
cluster2 ON 0 0 0 0 A N -
----------------------------------------------------------------------
ACTIVE-COPIES
LIBRARY RUN DEF
cluster0 0 0
cluster1 0 0
cluster2 0 0
----------------------------------------------------------------------
LIBRARY CODE-LEVELS
cluster0 8.41.269.6810
cluster1 8.41.200.41
cluster2 8.41.269.6810
LIBRARY REQUEST,composite_library,LVOL,volser
This command allows an operator on the host to obtain the information the grid stores about a particular logical volume. This command can be used when you do not want to use the TS7700 MI to display the logical volume information. Sample output for this command is shown in Example 10-11.
Example 10-11 LI REQ,libname,LVOL,volser
LI REQ,ATL3484F,LVOL,HYD101 CBR1020I Processing LIBRARY command: REQ,ATL3484F,LVOL,HYD101.
CBR1280I Library ATL3484F request. 478
Keywords: LVOL,HYD101
----------------------------------------------------------------------
LOGICAL VOLUME INFORMATION V4 .1
LOGICAL VOLUME: HYD101
MEDIA TYPE: ECST
COMPRESSED SIZE (MB): 13
MAXIMUM VOLUME CAPACITY (MB): 1000
CURRENT OWNER: cluster0
MOUNTED LIBRARY:
MOUNTED VNODE:
MOUNTED DEVICE:
TVC LIBRARY: cluster0
MOUNT STATE:
CACHE PREFERENCE: PG0
CATEGORY: 000F
LAST MOUNTED (UTC): 2017-10-02 14:49:11
LAST MODIFIED (UTC): 2017-10-02 14:46:32
LAST MODIFIED VNODE: 00
LAST MODIFIED DEVICE: 00F0
TOTAL REQUIRED COPIES: 2
KNOWN CONSISTENT COPIES: 2
KNOWN REMOVED COPIES: 0
IMMEDIATE-DEFERRED: N
DELETE EXPIRED: N
RECONCILIATION REQUIRED: N
LWORM VOLUME: N
FLASH COPY: NOT ACTIVE
---------------------------------------------------------------------
LIBRARY RQ CACHE PRI PVOL SEC PVOL COPY ST COPY Q COPY CP REM
cluster0 N N A02014 ------ CMPT - SYNC N
cluster1 N Y ------ ------ CMPT - SYNC N
cluster2 N N ------ ------ NOT REQ - NO COPY N
---------------------------------------------------------------------
LIBRARY CP
cluster0 0
cluster1 0
cluster2 0
10.1.4 Library LMPOLICY command
Use the LIBRARY LMPOLICY command to assign or change a volume’s policy names outboard at the library. You can use this command only for private, library-resident volumes that are in a library that supports outboard policy management.
The processing for the LIBRARY LMPOLICY command runs the Library Control System (LCS) external services FUNC=CUA function. Any errors that the Change Use Attribute (CUA) interface returns can also be returned for the LIBRARY LMPOLICY command. If the change use attribute installation exit (CBRUXCUA) is enabled, the CUA function calls the installation exit. This can override the policy names that you set by using the LIBRARY LMPOLICY command.
The results of this command are specified in the text section of message CBR1086I. To verify the policy name settings and to see whether the CBRUXCUA installation exit changed the policy names you set, display the status of the volume.
The syntax of the LIBRARY LMPOLICY command to assign or change volume policy names is shown in Example 10-12.
Example 10-12 LIBRARY LMPOLICY command syntax
LIBRARY|LI LMPOLICY|LP ,volser ,SG= Storage Group name |*RESET*
,SC= Storage Class name |*RESET*
,SC= Storage Class name |*RESET*
,MC= Management Class name |*RESET*
,DC= Data Class name |*RESET*
The following parameters are required:
•LMPOLICY | LP
Specifies a request to set one or more of a private volume’s policy names in the TS7700.
•Volser
Volser specifies the volume serial number of a private volume that is in a TS7700.
•You must specify at least one of the following optional parameters. These parameters can be specified in any order:
– SG={Storage Group name | *RESET*}
Specifies a construct name for the SG parameter
Specifies a construct name for the SG parameter
– SC={Storage Class name | *RESET*}
Specifies a construct name for the SC parameter
Specifies a construct name for the SC parameter
– MC={Management Class name | *RESET*}
Specifies a construct name for the MC parameter
Specifies a construct name for the MC parameter
– DC={Data Class name | *RESET*}
Specifies a construct name for the DC parameter
Specifies a construct name for the DC parameter
If the request is successful, the construct name is changed to the requested name. If you specify the *RESET* keyword, you are requesting that OAM set this construct to the default, which is blanks.
The values that you specify for the SG, SC, MC, and DC policy names must meet the storage management subsystem (SMS) naming convention standards:
•Alphanumeric and national (special) characters only
•Name must begin with an alphabetical or national (special) character ($, *, @, #, or %)
•No leading or embedded blanks
•Eight characters or less
10.1.5 Useful DEVSERV QUERY commands
Some of the most useful DEVSERV QUERY commands are described in this section.
DEVSERV QTAPE command
The DEVSERV QTAPE or DS QT command allows a query of the basic configuration of the SMS tape library as it has been defined in the input/output definition file (IODF). With the RDC operand, it is useful for viewing the Composite Library ID and libport ID associated with a device.
|
Note: The DS QT command with the QHA operand can display which systems and SYSplexs are connected to a specific device in a cluster. For more information, see 10.8.2, “Additional commands built to support CUIR functionality” on page 606.
|
The following command shows the syntax:
DS QT,devnum,1,RDC
The following are the values in the command:
DS Device service
QT Query tape
devnum Device address
1 Number of devices to be displayed
RDC Read device characteristics
Figure 10-1 shows the output of a DS QT system command.
Figure 10-1 Sample DEVSERV QT command output
|
Clarification: The distributed library number or cluster index number for a given logical drive can be determined with the DS QT command. As identified in Figure 10-1, the response shows LIBPORT-ID 01 for logical drive 9600. LIBPORT-ID 01 is associated with Cluster 0. The association between distributed libraries and LIBPORT-IDs is discussed in 6.4.1, “Defining devices through HCD” on page 230.
|
From the DS QT command in Figure 10-1, you can derive the LIBRARY-ID for the composite library and the LIBPORT-ID of the logical control unit (LCU) presenting the logical device.
The real device type of the physical devices is unknown to the host, and DEVSERV always shows 3592 as DEVTYPE. The LIBID field identifies the composite library ID associated with the device.
The real device type of the physical devices is unknown to the host, and DEVSERV always shows 3592 as DEVTYPE. The LIBID field identifies the composite library ID associated with the device.
|
Tip: You can get the device type of the backend physical drives of a distributed library from the following LI REQ command:
LI REQ,<distributed library name>,PDRIVE
|
On the z/OS host, the new option QHA (Query Host Access to volume) has been added to the existing DEVSERV QTAPE command. This option allows the command to surface which systems and SYSplexs are connected to a specific device in a cluster. For a full description of the syntax and output of the new command, see “DEVSERV QTAPE,xxxx,QHA” on page 610.
DEVSERV QLIB,CATS command
The command DS QLIB,CATS allows you to view and change logical VOLSER categories without need to initial program load (IPL) the system. Example 10-13 shows how to list all of the categories that are used in a system.
Example 10-13 Sample output of DEVSERV QLIB,CATS
DS QL,CATS
IEE459I 10.56.27 DEVSERV QLIB 626
5001 5002 5003 5004 5005 5006 5007 5008 5009 500A 500B 500C 500D
500E 500F
After you have the actual categories, you can change them. To perform this task, you can change the first 3 digits of the category. However, the last digit must remain unchanged because it represents the media type. Example 10-14 shows the command that changes all categories to 111 for the first 3 digits.
Example 10-14 Sample output of DEVSERV QLIB,CATS(111*)
DS QL,CATS(111*)
IEE459I 10.57.35 DEVSERV QLIB 899
1111 1112 1113 1114 1115 1116 1117 1118 1119 111A 111B 111C 111D
111E 111F
Ensure that this change is also made in the DEVSUPxx PARMLIB member. If it is not, the next IPL reverts categories to what they were in DEVSUPxx. For a further description of changing categories, see 10.5, “Effects of changing volume categories” on page 603.
DEVSERV QLIB,LIST command
Example 10-15 shows how you list all of the active composite libraries by using the DS QL,LIST command. The QLIB command uses the LIBRARY-IDs (LIBIDs), not the TAPE LIBRARY NAME that was used in the D SMS,LIB command.
Example 10-15 DEVSERV QLIB,LIST
DS QL,LIST
IEE459I 09.39.33 DEVSERV QLIB 933
The following are defined in the ACTIVE configuration:
*BA062 *CA045 *BA060 *BA045 *BA003 *BA031 *BA032 *BA002 *BA039 *BA038
*BA010 BA066 BA051 BA004
|
Note: The asterisks in the QLIB displays indicate libraries that are attached to the host.
|
For a complete description of all of the DS QLIB commands, see Appendix D, “DEVSERV QLIB command” on page 849.
10.1.6 Scratch volume recovery for volumes
If you determine that a volume was mistakenly returned to scratch, you can sometimes return the volume to private status to recover its contents. If EXPIRE HOLD has been ENABLED, the volume will not be eligible to be reused before the EXPIRE time has been reached. The method to recover depends on the TMS used. In general, change the volume’s status from scratch to private, and change the expiration date in the TMS by adding at least one week. Doing so prevents the TMS from returning the volume to scratch during the next few days. Further details follow about how to recover a logical volume that was scratched in error.
Checking a VOLSER to determine whether it has been reused
The first step in determining whether a volume can be recovered is to check that the VOLSERs that you want to recover have not already been reused to satisfy a SCRATCH mount. Issue the D SMS,VOL(volser) command for each volume that you want to check on. See Example 10-16.
Example 10-16 Check whether VOLSERs are still available
D SMS,VOL(A0000P)
CBR1180I OAM tape volume status: 095
VOLUME MEDIA STORAGE LIBRARY USE W C SOFTWARE LIBRARY
TYPE GROUP NAME ATR P P ERR STAT CATEGORY
A0000P MEDIA2 *SCRTCH* HYDRAG S N N NOERROR SCRMED2
USE ATR of S indicates that the volume is still in SCRATCH status and has not yet been reused. Therefore, you have a chance to recover the volume contents if there is a consistent copy in the TS7700. If the display for this command says USE ATR of P, it has been reused and you cannot recover the contents of the volume by using host software procedures.
Checking for a consistent copy of the volume
The second step in determining whether a volume can be recovered is to check that the VOLSERs that you want to recover have a consistent copy that is in the TS7700 somewhere. The best command to use to check field-known consistent copies is the LI REQ,composite-library,LVOL,volser command, as shown in Example 10-17.
Example 10-17 Check for a consistent copy
LI REQ,HYDRAG,LVOL,A0000P
LOGICAL VOLUME INFORMATION V4 0.1
LOGICAL VOLUME: A0000P
MEDIA TYPE: ECST
COMPRESSED SIZE (MB): 627
MAXIMUM VOLUME CAPACITY (MB): 4000
CURRENT OWNER: 00001
.
CATEGORY: 0022
LAST MOUNTED (UTC): 2014-10-02 15:29:28
LAST MODIFIED (UTC): 2014-10-02 15:29:04
LAST MODIFIED VNODE: 00
LAST MODIFIED DEVICE: 000B
TOTAL REQUIRED COPIES: 1
KNOWN CONSISTENT COPIES: 1
If KNOWN CONSISTENT COPIES is zero, you cannot recover this volume because it has been DELETE EXPIRED already.
Changing STATUS of scratched volumes to PRIVATE
The next step in recovering the volumes is to change the status from SCRATCH back to PRIVATE in the TS7700 and the TCDB. The next steps will vary depending on your TMS. If your TMS is DFSMS Removable Media Manager (DFSMSrmm), you will also change the status of the volume to MASTER in the RMM CDS.
To start this process, use DFSMSrmm to search on a volume string. Then, put all of the scratch volumes matching that string into a file with a TSO subcommand to change their status back to MASTER, and set an Expiration Date to some future value (to prevent the next run of DFSMSrmm Housekeeping from sending the volume back to SCRATCH), as shown in Example 10-18.
Example 10-18 Change status
//STEPA EXEC PGM=IKJEFT01
//SYSTSPRT DD DUMMY
//RMMCLIST DD DSN=DENEKA.RMMCV,
// DISP=(NEW,CATLG,DELETE),
// SPACE=(CYL,(2,2),RLSE),
// UNIT=SYSDA
//SYSTSIN DD *
PROF NOMSGID
RMM SV VOLUME(A*) OWNER(*) LIM(1) HOME(HYDRAG) STATUS(SCRATCH) -
CLIST('RMM CHANGEVOLUME ',' STATUS(MASTER) EXPDT(14355)
/*
The output in the RMMCLIST DD is as follows:
READY
RMM CHANGEVOLUME A0000P STATUS(MASTER) EXPDT(14355)
Use the job control language (JCL) shown in Example 10-19 to run the previously generated CLIST. This process can be done in the same job as the RMM SV command if no editing of the generated list was needed to remove volumes without a consistent copy found. Altering the status of such volumes to MASTER needlessly uses a scratch volser because the volume contents have already been expire-deleted.
Example 10-19 JCL for CLIST
//STEPB EXEC PGM=IKJEFT01,DYNAMNBR=60
//SYSTSPRT DD DSN=DENEKA.RMMCV.OUT,
// DISP=(NEW,CATLG,DELETE),
// SPACE=(CYL,(10,2),RLSE),
// UNIT=SYSDA
//SYSTSIN DD DISP=SHR,
// DSN=DENEKA.RMMCV
Setting the volume back to MASTER status in RMM will cause the CBRUXCUA (Change Use Attribute) installation exit to be started. If the change is approved, OAM will first update the volume category in the TS7700 to match the private category used by this host. After this process is successful, it will change the volume from scratch to private in the TCDB. These three sources (the library, TCDB, and TMS) must have consistent information for the status of the volume in order for a future mount of that volume to succeed.
The D SMS,VOL command can now be used to verify that the VOLSER was changed from S to P, as shown in Example 10-20.
Example 10-20 Verify the change
D SMS,VOL(A0000P)
VOLUME MEDIA STORAGE LIBRARY USE W C SOFTWARE LIBRARY
TYPE GROUP NAME ATR P P ERR STAT CATEGORY
A0000P MEDIA2 SGG00001 HYDRAG P N N NOERROR PRIVATE
10.1.7 Ejecting logical volumes
Logical volumes are not physical entities that can be individually removed from the library. They can also exist on physical stacked volumes that contain many other logical volumes. An EJECT should only be issued for a logical volume in the TS7700 if the intent is to delete the volume from the TS7700.
Because of the permanent nature of EJECT, the TS7700 allows you to EJECT only a logical volume that is in either the INSERT or SCRATCH category. If a logical volume is in any other status, the EJECT fails. If you eject a scratch volume, you cannot recover the data on that logical volume.
|
Tip: If a logical volume is in the error category (which is by default 000E), it must first be moved back to a scratch category before an EJECT can be successful. To move it, use ISMF ALTER to move it from the SCRATCH to SCRATCH category.
|
Volumes that are in the INSERT status can also be ejected by the resetting of the return code through the CBRUXENT exit. This exit is provided by your tape management system vendor. Another way to EJECT cartridges in the INSERT category is by using the MI. For more information, see “Delete Virtual Volumes window” on page 416.
After the tape is in SCRATCH status, follow the procedure for EJECT processing specified by your tape management system vendor. For DFSMSrmm, issue the RMM CHANGEVOLUME volser EJECT command.
If your tape management system vendor does not specify how to do this, you can use one of the following commands:
•The z/OS command LIBRARY EJECT,volser
•ISMF EJECT line operator for the tape volume
The EJECT process fails if the volume is in another status or category. For libraries managed under DFSMS system-managed tape, the system command LIBRARY EJECT,volser sent to a logical volume in PRIVATE status might fail with this message:
CBR3726I Function incompatible error code 6 from library <library-name> for volume <volser>
|
Clarification: In a DFSMS system-managed tape environment, if you try to eject a logical volume and get this error, the TMS might have already marked this volume as being ejected. This error is because the EJECT process first invokes the CBRUXEJC exit to allow or deny the EJECT request, which is normally written to invoke the TMS. If the TMS allows the EJECT request to be processed, it marks the volume as being ejected before the actual EJECT being issued to the library. Therefore, it is possible for the TMS and library/TCDB to become out-of-sync when processing EJECTs if the library later fails the EJECT.
|
If your tape management system is DFSMSrmm, you can use the commands that are shown in Example 10-21 to clean up the Removable Media Management (RMM) control data set (CDS) for failed logical volume ejects, and to resynchronize the TCDB and RMM CDS.
Example 10-21 Clean up the RMM CDS
RMM SEARCHVOLUME VOL(*) OWN(*) LIM(*) INTRANSIT(Y) LOCATION(vts) -
CLIST('RMM CHANGEVOLUME ',' LOC(vts)')
EXEC EXEC.RMM
CLIST('RMM CHANGEVOLUME ',' LOC(vts)')
EXEC EXEC.RMM
The first RMM command asks for a list of volumes that RMM thinks it has ejected, and
writes a record for each in a sequential data set called prefix.EXEC.RMM.CLIST. The CLIST then checks whether the volume is still resident in the VTS library and, if so, it corrects the RMM CDS.
writes a record for each in a sequential data set called prefix.EXEC.RMM.CLIST. The CLIST then checks whether the volume is still resident in the VTS library and, if so, it corrects the RMM CDS.
Issuing a large number of ejects at one time can cause some resource effect on the host. A good limit for the number of outstanding eject requests is no more than 10,000 per system. More ejects can be initiated when others complete. The following commands can be used on the IBM Z hosts to list the outstanding and the active requests:
F OAM,QUERY,WAITING
F OAM,QUERY,ACTIVE
10.2 Messages from the library
This section describes TS7700 enhanced message support and relevant messages.
10.2.1 CBR3750I Console Message
When the host receives a message from the library that is either informational or indicates an abnormal condition of some type, the host will surface this message (using OAM) within the CBR3750I message. This message has the following format:
CBR3750I Message from library library-name: message.
This indicates that a message has been sent from library library-name. Either the operator, at the library manager console has entered a message that is to be broadcast to the host, or the library itself, has broadcast a message to the host to relay status information or report an error condition. A list of the messages that can be broadcast from the library to the host is contained in the IBM TS7700 Series Operator Informational Messages White Paper, which can be accessed at the following website:
If additional assistance is required regarding the contents of the messages surfaced, engage IBM hardware support. The only role that OAM provides is to surface on the host the library-generated message through the CBR3750I message.
With OAM APAR OA52376 and R4.1.2 installed on all the clusters in a grid, this message has been enhanced to surface the severity impact text (INFORMATION, WARNING, IMPACT, SERIOUS, or CRITICAL) associated with each library message as documented in the white paper noted above. This text prevents you from having to reference the white paper to determine the severity associated with a particular library message, and results in the format for the CBR3750I message being updated as follows:
CBR3750I Message from library library-name: message. Severity impact: severity impact text.
You can optionally modify the severity impact text for each message through the TS7700 MI if you feel a different severity impact text is more applicable in your environment. If you choose to do so, an “*” is added to the severity impact text as follows:
CBR3750I Message from library library-name: message. Severity impact: severity impact text*.
In addition, each library message can now optionally be associated with a free-form customer impact text through the TS7700 MI. You can use this functionality to surface additional information that might be relevant for a particular library message in your environment. If a customer impact text is defined to a library message, the associated CBR3750I message is surfaced as follows:
CBR3750I Message from library library-name: message. Severity impact: severity impact text. Customer impact: customer-provided-impact-text.
10.2.2 TS7700 Host Console messages
Some abnormal conditions that occur in a TS7700 are not surfaced through the CBR3750I message. Rather, they are surfaced through their own unique message number in OAM. Some of the more common messages that you might see are listed below. For a complete and current list, see the appropriate release of z/OS MVS System Messages, Vol 4 (CBD-DMO).
Incompatibility error message
In an incompatible function error, you might see the message CBR3726I:
CBR3726I Function incompatible error code error-code from library library-name for volume volser.
In this message, an error has occurred during the processing of volume volser in library library-name. The library returned a unit check with an error code error-code, which indicates that an incompatible function has been requested. A command has been entered that requests an operation that is understood by the subsystem microcode, but cannot be run.
The explanation for the error-code can be found in the TS7700 Customer IBM Knowledge Center under Reference → Perform library function codes → Error recovery action codes → Function Incompatible.
Warning VTS operation degraded messages
When a VTS is operating in a degraded state, the following message is generated:
CBR3786E VTS operation degraded in library library-name
When the degradation is resolved, you see this message:
CBR3768I VTS operations in library library-name no longer degraded
Warning cache use capacity (TS7720)
For the TS7720, warning and critical cache free space messages are displayed:
CBR3792E Library library-name has entered the limited cache free space warning state.
CBR3794E Library library-name has entered the out of cache resources critical state.
When the cache situation is resolved, the following messages are shown:
CBR3793I Library library-name has left the limited cache free space warning state.
CBR3795I Library library-name has left the out of cache resources critical state.
Out of physical volumes
When a distributed library that is associated with a cluster runs out of scratch stacked physical volumes, operations of the TS7760T, TS7740, or TS7720T are affected. As part of normal processing, data is copied from cache to physical volumes in a primary pool that is managed by the TS7700. A copy might also be made to a physical volume in a secondary pool if the dual copy function is specified by using Management Class (MC).
Empty physical volumes are needed in a pool or, if a pool is enabled for borrowing, in the common scratch pool, for operations to continue. If a pool runs out of empty physical volumes and there are no volumes that can be borrowed, or borrowing is not enabled, operations that might use that pool on the distributed library must be suspended.
If one or more pools run out of empty physical volumes, the distributed library enters the Out of Physical Scratch state. The Out of Physical Scratch state is reported to all hosts attached to the cluster associated with the distributed library and, if included in a grid configuration, to the other clusters in the grid.
The following MVS console message is generated to inform you of this condition:
CBR3789E VTS library library-name is out of empty stacked volumes.
Library-name is the name of the distributed library in the state. The CBR3789E message remains on the MVS console until empty physical volumes are added to the library, or the pool that is out has been enabled to borrow from the common scratch pool and there are empty physical volumes to borrow. Intervention-required conditions are also generated for the out-of-empty-stacked-volume state, and for the pool that is out of empty physical volumes.
If the option to send intervention conditions to attached hosts is set on the TS7700 that is associated with the distributed library, the following console messages are also generated to provide specifics about the pool that is out of empty physical volumes:
CBR3750I Message from library library-name: OP0138 The Common Scratch Pool (Pool 00) is out of empty media volumes.
CBR3750I Message from library library-name: OP0139 Storage pool xx is out of scratch volumes.
The OP0138 message indicates the media type that is out in the common scratch pool. These messages do not remain on the MVS console. The intervention conditions can be viewed through the TS7700 MI.
If the TS7760T, TS7740, or TS7720T is in a grid configuration, and if its associated distributed library enters the out-of-empty-stacked-volume state, operations are affected in other ways:
•All copy operations are immediately suspended in the cluster (regardless of which pool has become empty).
•If the cluster has a Copy Consistency Point of RUN, the grid enters the Immediate Mode Copy Operations Deferred state, and an MVS console message is generated:
CBR3787E One or more immediate mode copy operations deferred in library
library-name.
•If another cluster attempts to copy a logical volume that is not resident in the cache, the copy attempt fails.
•The grid prefers clusters that are not in the out-of-empty-stacked-volume state in choosing a TVC cluster, but the grid can still select a remote TVC whose cluster is in that state. If the data needed is not in the remote cluster’s TVC, the recall of the data fails. If data is being written to the remote cluster’s TVC, the writes are allowed.
However, because there might not be any empty physical volumes available to copy the data to, the cache might become full of data that cannot be copied. In this case, all host I/O that uses that cluster’s TVC becomes throttled to prevent a cache overrun.
Monitor the number of empty stacked volumes in a library. If the library is close to running out of a physical volume media type, either expedite the reclamation of physical stacked volumes or add more volumes. You can use the Bulk Volume Information Retrieval (BVIR) function to obtain the physical media counts for each library. The information that is obtained includes the empty physical volume counts by media type for the common scratch pool and each
defined pool.
defined pool.
If your Pool properties have a Second Media that is defined, and the primary media type is exhausted, the library does not go into degraded status for out of scratch.
Above Threshold Warning state
The TS7760T, TS7740, or TS7720T enters the Above Threshold Warning state when the amount of data to copy exceeds the threshold for the installed cache capacity for five consecutive sample periods (the amount of data to copy is sampled every 30 seconds). The TS7760T, TS7740, or TS7720T leaves the Above Threshold Warning state when the amount of data to premigrate is below the threshold capacity for 30 consecutive sample periods. The consecutive sampling criteria is to prevent excessive messages from being created.
This state produces the following message:
CBR3750I Message from library library-name:OP0160 Above threshold for uncopied data in cache, throttling possible
10.3 EXPIRE HOLD and scratch processing considerations
This topic deals with the interaction of SCRATCH processing and the EXPIRE settings on the TS7700. The topics of EXPIRE time and EXPIRE HOLD were introduced in 2.3.21, “Expired virtual volumes and the Delete Expired function” on page 80, and should be referenced for a basic understanding of these two settings. Consider the following cases:
•EXPIRE HOLD option is enabled and the TS7760T, TS7740, or TS7720T is low on scratch volumes.
•EXPIRE HOLD option is enabled and Cache Utilization is beyond the wanted threshold in the TS7760D or TS7720D.
10.3.1 EXPIRE HOLD and low on scratch tapes in TS7760T, TS7740, or TS7720T
The EXPIRE HOLD option is used to ensure that a logical volume that is sent to the SCRATCH pool cannot be reused or deleted before the grace period that is specified as the EXPIRE time has passed. This fact can sometimes create a problem where the library might run out of available volumes to satisfy mount requests to write new data. If the EXPIRE time has been set too long and there are not enough logical volumes being released to keep a healthy level of SCRATCH volumes available, it might be necessary to reduce the EXPIRE time.
However, this change affects only new volumes that are going into the SCRATCH pool. The existing volumes in the pool continue to be held until the original EXPIRE time has passed. However, if EXPIRE HOLD is cleared, these volumes can then be added to the candidate list for SCRATCH mounts. Therefore, clearing the EXPIRE HOLD option immediately helps to alleviate the low on scratch condition, but it no longer protects data that has inadvertently been sent to SCRATCH. The recovery of user data on volumes in the SCRATCH pool might no longer be certain.
10.3.2 EXPIRE HOLD and cache utilization in TS7760D or TS7720D
When the EXPIRE HOLD option is enabled, the cache in a TS7700 is used up in part by holding data from logical volumes that have been sent to the SCRATCH pool. In addition to the risk of running out of logical volumes to mount, there is a risk of running out of cache in a TS7760D or TS7720D when AUTOREMOVAL is not enabled.
Again, EXPIRE time should be considered, and if a TS7760D or TS7720D is consistently running high on cache utilization, adjust this EXPIRE time. In this case, the clearing of the EXPIRE HOLD setting does not immediately alleviate the high cache utilization condition. The effect of disabling the EXPIRE HOLD from the cache perspective is to enable volumes in the SCRATCH pool to begin entering the candidate list for expire delete processing.
Once per hour, a task runs in the library that processes some number of volumes from this list, and reduces cache utilization by deleting the expired volumes from cache. The number of volumes that are deleted per hour is by default 1000. The number of volumes that are moved to this candidate list is customizable (1000 - 2000), and is controlled by using the
LI REQ,composite-library,SETTING,DELEXP,COUNT,value command that is documented in 10.1.3, “Host Console Request function” on page 588, and in the following white paper:
LI REQ,composite-library,SETTING,DELEXP,COUNT,value command that is documented in 10.1.3, “Host Console Request function” on page 588, and in the following white paper:
The EXPIRE time is the grace period that enables the recovery of the data in the case of procedural error. Careful consideration needs to be made to ensure that this value is long enough to allow for such errors to be detected, and the data recovered, before the DELETE EXPIRE process removes the logical volume permanently.
10.4 Scratch count mismatch
There is often some discrepancy between the values reported for scratch counts from various sources (TS7700 MI, TCDB, TMS). To obtain the number of usable scratch volumes in the TS7700, issue the D SMS,LIBRARY(libname),DETAIL command. In addition to providing other information about the designated tape library, this command reports the number of usable scratch volumes. This value is obtained directly from the TS7700 and surfaced within the CBR1110I message.
When EXPIRE HOLD is in effect, the total number of scratch volumes differs from the total number of usable SCRATCH volumes because volumes for which the EXPIRE time has not yet elapsed are not eligible to be selected to satisfy a SCRATCH mount request. For this reason, the most accurate source of scratch counts for a TS7700 is always the output from the D SMS,LIBRARY(libname),DETAIL command.
10.5 Effects of changing volume categories
As described in 4.3, “Planning for software implementation” on page 171, categories are assigned to volumes in the library according to the DEVSUPxx parmlib member on the host that performs cartridge entry processing for those volumes. The category assignment for a volume is stored in the library manager. Although the host has no knowledge of the category of a specific volume, this information can be surfaced on the host by using the D SMS,VOLUME(volser) command. The output of this command includes the LM CATEGORY field that surfaces the category assigned to that volume in the library manager.
The categories to be assigned by the host can be changed dynamically by using the DEVSERV QLIB,CATS command or by modifying the values specified in the DEVSUPxx member and IPLing.
Special consideration should be given to the effects that the change will have on the host. The most common problem is that, after the change, users might forget that all of the logical volumes in the scratch pool still belong to the initially defined categories. If no volumes have been assigned the new categories, requests for scratch mounts will fail and OAM will surface the CBR4105I and CBR4196D messages.
There are several ways to resolve such an issue. If the categories were changed because there is a desire to partition the library, then a new scratch pool must be created for this host by adding a range of volumes that will be accepted by the TMS during cartridge entry processing. If the old scratch pool was intended to be used by this host, then the category of a single volume or range of volumes can be updated by using the ISMF panes to ALTER one or more use attributes from SCRATCH to SCRATCH.
This step sets the category of the volume in the library manager to match the associated newly defined category on the host. If a large range of volumes needs to be changed, consider using the CBRSPLCS utility to perform such a change. For more information about how to use this utility, see z/OS DFSMS Object Access Method Planning, Installation, and Storage Administration Guide for Tape Libraries, SC23-6867.
A modification of the volume entries in the TCDB using IDCAMS does not change the categories that are stored in the library manager and should not be used for this purpose.
10.6 Library messages and automation
There are some messages that can be useful to capture by automation. In particular, there are three that represent issues with the library being unable to call home. All library messages, including these three, are prefaced with CBR3750I:
•OP0463: A TSSC error has occurred. The TSSC is unable to call home.
•OP0625: A system reboot interrupted a call home.
•OP0550: Service Call Home, TSSC was unable to generate a PMR number.
The advised action for these messages is to contact the service center and engage support to determine why the call home was being attempted.
10.7 Mount Retry (R4.1.2 Enhancement)
When a mount fails today, certain error conditions are considered retry-able. If they are considered retry-able, the following message is issued:
CBR4196D Job job-name, drive device-number, volser volser, error code error-code. {Reply ‘R’ to retry or ‘C’ to cancel. | Reply ‘R’ to retry, ‘W’ to wait or ‘C’ to cancel.}
The CBR4196D message is issued along with messages describing the error condition, such as the following example:
CBR4195I LACS retry possible for job VTNCMP: 015
IEE763I NAME= CBRLLACS CODE= 140169
CBR4000I LACS MOUNT permanent error for drive 0BCA.
CBR4105I No MEDIA2 scratch volumes available in library TVL10001.
IEE764I END OF CBR4195I RELATED MESSAGES
*06 CBR4196D Job VTNCMP, drive 0BCA, volser SCRTCH, error code 140169.
Reply ‘R’ to retry or ‘C’ to cancel.
With OAM APAR OA52376 applied, you can instruct OAM to automate the mount’s retry function. This function is specified by using the existing SETTLIB command in the CBROAMxx startup parmlib member, and is controlled by three new parameters:
•LACSRETRYTIMES(1-9): Specifies the number of times to automatically retry the mount
•LACSRETRYMINUTES(1-9): Specifies the number of minutes between each automatic retry
•LACSRETRYFAIL(YES|NO): Specifies whether the mount should be failed or the CBR4196D surfaced
The full syntax of the command that can be specified is:
SETTLIB LACSRETRYTIMES(X) LACSRETRYMINUTES(Y) LACSRETRYFAIL(YES|NO)
You can use different combinations of these three parameters to control how OAM will automatically respond to retry-able mount failures. The following are the possible OAM responses:
•Retry the mount a number of times (LACSRETRYTIMES), every number of minutes LACSRETRYMINUTES. If the mount has not yet succeeded at the end of the retry processing, surface the CBR4196D (LACSRETRYFAIL(NO)).
•Retry the mount a number of times (LACSRETRYTIMES), every number of minutes LACSRETRYMINUTES. If the mount has not yet succeeded at the end of the retry processing, fail the mount request (LACSRETRYFAIL(YES)). No CBR4196D is issued.
•Fail the mount immediately (LACSRETRYFAIL(YES)). No CBR4196D is issued.
•Issue the CBR4196D as is done today. LACSRETRYFAIL(NO) or no parameters specified.
10.7.1 Enhanced Mount Retry Defaults
The only set default for these parameters is LACSRETRYFAIL(NO), which is set regardless of whether any of these parameters are defined in the CBROAMxx parmlib member. The LACSRETRYTIMES and LACSRETRYMINUTES parameter values only receive default values if one of these parameters is specified without the other. For example, if only LACSRETRYMINUTES is specified, LACSRETRYTIMES is set to 6. Alternatively, if only LACSRETRYTIMES is specified, LACSRETRYMINUTES is set to 2. If you are using this function, specify both LACSRETRYTIMES and LACSRETRYMINUTES to avoid confusion.
10.7.2 Enhanced Mount Retry Example
For a retry-able error in which automatic retry has been specified, the following will be displayed (as an example) if the values specified are LACSRETRYTIMES(6) LACSRETRYMINUTES(2) and either LACSRETRYFAIL(Y/N):
CBR4195I LACS retry possible for job VTNCMP: 015
IEE763I NAME=CBRLLACS CODE=140169
CBR4000I LACS MOUNT permanent error for drive 0BCA
CBR4105I No MEDIA2 scratch volumes available in library TVL10001.
IEE764I END OF CBR4195I RELATED MESSAGES
CBR4197D Job VTNCMP, drive 0BCA, volser SCRTCH, code 140169.
Retrying every 2 minutes, 6 times. Reply ‘C’ to cancel.
As shown above, a new message, CBR4197D, will also be surfaced so you can cancel out of the automatic retry. If the mount is canceled, the LACSRETRYFAIL specification is not used and the mount will be failed immediately.
If, after the six retries every two minutes (for a total of 12 minutes of retry processing), the mount has not been satisfied, the following message will be issued if LACSRETRYFAIL is set to YES:
IEE763I NAME=CBRLLACS CODE= 140169
CBR4000I LACS MOUNT permanent error for drive 0BCA.
CBR4105I No MEDIA2 scratch volumes available in library TVL10001.
IEE764I END OF IEC147I RELATED MESSAGES
This is the same set of messages that would be issued if the mount is not considered to be retry-able, or if the CBR4196D message is responded to with “C”. Otherwise, if LACSRETRYFAIL is set to NO, the CBR4196D message is issued as shown above.
For more information about this enhancement, see OA52376.
10.8 CUIR for Tape (R4.1.2 Enhancement)
Before a TS7700 cluster can be placed into service today, in addition to other manual tasks, a customer must vary offline the devices in that cluster to each host connected to that cluster. Because this can be a time consuming process, R4.1.2 includes a new feature called Control Unit Initiated Reconfiguration (CUIR) that helps with this process.
When R4.1.2 is installed on each cluster in a grid, CUIR can detect that a cluster in the grid is entering service. It then signals to each host connected to that cluster that the host needs to vary offline any devices that the host has online to that cluster. If the z/OS host has OA52376 installed, it receives this signal and attempts to vary offline the devices in the cluster. Any long running jobs will need to be canceled or swapped to another cluster to ensure that the device transitions from “pending offline” to “offline”.
When a device is varied offline by this CUIR functionality, it is known as being “offline for CUIR reasons”. After the cluster is no longer in service mode, it can notify each connected host that the status has changed and each host can vary those devices that were “offline for CUIR reasons”, back online.
10.8.1 LIBRARY REQUEST commands to enable/disable CUIR
The signaling of the host by the cluster when the cluster is entering service mode is enabled/disabled through a new LIBRARY REQEST command that has the following syntax:
LIBRARY REQUEST,library-name,CUIR,SETTING,{SERVICE|FENCE|ALL},{ENABLE|DISABLE}
The signaling of the host by the cluster when the cluster is no longer in service mode is enabled/disabled through another new LIBRARY REQUEST command that has the following syntax:
LIBRARY REQUEST,library-name,CUIR,AONLINE,{SERVICE|FENCE|ALL},{ENABLE|DISABLE}
In each command above, library-name is the name of the composite library as defined in SMS on the z/OS host. For the 4.1.2 release, the keyword FENCE is not yet supported. If it is used on one of these LIBRARY REQUEST commands, the grid returns an error message.
|
Note: The FENCE keyword is not support in R4.1.2. If ALL is specified, only the SERVICE setting is affected.
|
10.8.2 Additional commands built to support CUIR functionality
To support the CUIR functionality that was introduced in 4.1.2, the following commands have been created:
LIBRARY REQUEST,library-name,LDRIVE
LIBRARY REQUEST,library-name,LDRIVE,group,index
DS QT,xxxx,QHA
LIBRARY DISPDRV,library-name
VARY device-number,ONLINE,RESET
This section discusses each of these commands and provides the syntax, output, and keyword descriptions for each.
LIBRARY REQUEST,library-name,LDRIVE
On the TS7700 side, a new keyword, LDRIVE, has been added to the existing LIBRARY REQUEST command. This keyword allows logical drive information (including CUIR-specific information) associated with a cluster (distributed library) or grid (composite library) to be surfaced. It can be used to better understand what systems that manual vary commands might need to be issued for, to track the status of a CUIR request from a TS7700, and to verify the functions that the cluster or grid is enabled for. This command has the following syntax:
LIBRARY REQUEST,library-name,LDRIVE
The output for the command has the following syntax when issued against a composite library:
Logical Drive Status Information V1 .0
Composite Library View
Current Time (UTC): yyyy-mm-dd hh:mm:ss
Service Vary: Enabled|Disabled Auto Online: Enabled|Disabled
Unhealthy Vary: Enabled|Disabled Auto Online: Enabled|Disabled
XXXXX (CL0)
Assigned/Grouped/Total Devices: nnnn/nnnn/nnnn
Assigned/Grouped/Total LPARS: nnnn/nnnn/nnnn SSV: nnnn SUV: nnnn
Active Service Vary: Y|N
Active Unhealthy Vary: Y|N
XXXXX (CL1)
Assigned/Grouped/Total Devices: nnnn/nnnn/nnnn
Assigned/Grouped/Total LPARS: nnnn/nnnn/nnnn SSV: nnnn SUV: nnnn
Active Service Vary: Y|N
Active Unhealthy Vary: Y|N
... ...
XXXXX (CL7)
Assigned/Grouped/Total Devices: nnnn/nnnn/nnnn
Assigned/Grouped/Total LPARS: nnnn/nnnn/nnnn SSV: nnnn SUV: nnnn
Active Service Vary: Y|N
Active Unhealthy Vary: Y|N
|
Note: Anything pertaining to “unhealthy vary” is there for future support and is not used with the R4.1.2 CUIR support.
|
The output keywords are defined as follows:
•Current Time: Current time stamp within TS7700 in Coordinated Universal Time.
•Service Vary: CUIR, SETTING, SERVICE setting.
•Auto Online: CUIR, SETTING, AONLINE, SERVICE setting.
•Unhealthy Vary: CUIR, SETTING, FENCE setting.
•Auto Online: CUIR, SETTING, AONLINE, FENCE setting.
•XXXXX (CLx): Cluster’s sequence number and cluster index.
•Assigned/Grouped/Total Devices: The count of the assigned, grouped, and total devices attached to this cluster.
•Assigned/Grouped/Total LPARS: The count of the assigned, grouped, and total LPARs attached to this cluster.
•SSV: The count of the LPARs that Support Service Vary attached to this cluster.
•SUV: The count of the LPARs that Support Unhealthy Vary attached to this cluster.
•Active Service Vary: If there are PGIDs that already received Automatic or Manual Vary Devices Offline attention for Service Prep on this cluster but an Automatic or Manual Vary Devices Online attention has not yet been surfaced, ‘Y’ is set.
•Active Unhealthy Vary: If there are PGIDs that already received Automatic Vary Devices Offline attention for the unhealthy cluster on behalf of the peer unhealthy (possibly SBND) cluster and the peer cluster has not yet surfaced an Automatic or Manual Vary Devices Online attention, ‘Y’ is set (and its remote cluster list).
The output for the command has the following syntax when issued against a distributed library:
Logical Drive Status Information V1 .0
Distributed Library View
Current Time (UTC): yyyy-mm-dd hh:mm:ss
XXXXX (CLx)
Service Vary: Enabled|Disabled Auto Online: Enabled|Disabled
Unhealthy Vary: Enabled|Disabled Auto Online: Enabled|Disabled
Assigned/Grouped/Total Devices: nnnn/nnnn/nnnn
Assigned/Grouped/Total LPARS: nnnn/nnnn/nnnn SSV: nnnn SUV: nnnn
Active Service Vary: Y|N
Active Unhealthy Vary: Y|N <cluster index list>
Active Path Group Indexes
list of indexes from 0-4095 separated by a single space (multiple rows possible)
The keywords for this command when issued against a distributed library are the same as when issued against a composite library, with the following addition:
•Active Path Group Indexes: The list of Active PGIDs
For more information, see the IBM TS7700 Series Control Unit Initiated Reconfiguration (CUIR) User’s Guide at:
LIBRARY REQUEST,library-name,LDRIVE,GROUP,index
When the additional GROUP parameter is specified on this command (along with an associated index listed from the distributed library output above), additional information can be obtained about an index (LPAR) attached to that distributed library. This version of the command has the following syntax:
LIBRARY REQUEST,library-name,LDRIVE,GROUP,index
The output for this command has the following syntax:
Logical Drive Path Group Information V1. 0
Distributed Library Pathing View
Current Time (UTC): yyyy-mm-dd hh:mm:ss
XXXXX (CLx)
Path Group ID Index: nnnn
SSV: YES|NO SUV: YES|NO
Path Group ID: xxxxxxxxxxxxxxxxxxxxxx
CSSID: xx LPARID: xx CPU SERIAL#: xxxx CPU Type: xxxx GUEST: YES|NO
System Name: {xxxxxxxx|UNKNOWN] Sysplex Name: {xxxxxxxx|UNKNOWN}
WWNN(CEC): xxxxxxxxxxxxxxxx Channel ID: xx
FICON Ports: FxPy FxPy FxPy FxPy FxPy FxPy FxPy FxPy
Paths [nnnn] nnnn nnnn nnnn ....
Assigned/Grouped/Total Devices: nnnn/nnnn/nnnn
Assigned & Grouped Devices
list of devices in assigned and grouped state
Grouped Only Devices
list of devices still in a grouped state (online or pending offline)
The output keywords are defined as follows:
•Current Time: Current time stamp within TS7700 in Coordinated Universal Time.
•XXXXX (CLx): Cluster’s sequence number and cluster index.
•Path Group ID Index: TS7700 internal path group index used to track host path groups.
•SSV: The count of the LPARs which Support Service Vary attached to this cluster (or whether supported by LPAR in other use cases).
•SUV: The count of the LPARs that Support Unhealthy Vary attached to this cluster (or whether supported by LPAR in other use cases).
•Path Group ID: Device Path Group ID for the specific LPAR (22 characters, also referred to as PGID):
– CSSID: Logical Channel Subsystem ID. A 1-byte number in the range of 0-5 representing the logical channel subsystem within a system zCEC. A single CSSID can contain one or more LPARs.
– LPARID: Logical Partition ID. A 1-byte number in the range of X’01’ to X’0F’ representing the LPAR partition within the CSSID.
– CPU SERIAL: zCEC CPU serial number.
– CPU Type: CPU or system zCEC type.
– GUEST: Determines whether this LPAR is a guest under z/VM or not.
•System Name: System Name for a specific LPAR.
•Sysplex Name: Parent Sysplex Name for a specific LPAR.
•WWNN: zCEC worldwide node name, which is a world unique ID per zCEC.
•Channel ID: Channel Image ID or a 1-byte user-defined number assigned to each LPAR within a zCEC. Although not required, this ID is often made up of the LPARID and CSSID combined. Valid values are from 0x01 - 0xFF (0x5F as of IBM z13®).
•FICON Ports: A list of FICON cards and their physical ports that have one or more logical paths established from the specific LPAR.
•Paths: The total number of paths followed by a list of the number of paths per FICON Port established from the specific LPAR.
•Assigned/Grouped/Total Devices: The count of the assigned, grouped, and total devices attached to this cluster by the specific LPAR. “Assigned” is the count of devices that have pathing assignment established, which in a z/OS configuration usually implies that it has a volume mounted. “Grouped” is the count of devices that are grouped by the LPAR, which in a z/OS configuration usually implies it is online. “Total” devices is the number of devices that have been grouped previously since the last LPAR IPL or cluster IML. If this count is larger than the “grouped” count, it usually implies one or more devices have been varied offline.
•Assigned and Grouped Devices: The list of assigned and grouped devices for this LPAR (PGID). These devices are likely active with a logical volume by this LPAR.
•Grouped Only Devices: The list of the grouped devices with this LPAR (PGID). These devices are likely those that are online from this LPAR.
For additional information about the output provided by the LDRIVE command and its subsets, see the IBM TS7700 Series z/OS Host Command Line Request User's Guide, which can be accessed at the following website:
DEVSERV QTAPE,xxxx,QHA
On the z/OS host, a new option, QHA (Query Host Access to volume) has been added to the existing DEVSERV QTAPE command. This option allows the command to surface which systems and SYSplexs are connected to a specific device in a cluster. The command has the following syntax:
DS QT,xxxx,QHA
The output for the command has the following syntax:
DEVSERV QTAPE,xxxx,QHA
IEE459I hh:mm:ss DEVSERV QTAPE
UNIT DTYPE DSTATUS CUTAPE DEVTYPE CU-SERIAL DEV-SERIAL ACL LIBID
xxxx aaaaa bbbbbbb ccccccc dddddddd eeee-eeeee ffff-fffff g hhhhh
QUERY HOST ACCESS TO DEVICE
PATH-GROUP-ID FLAGS STATUS SYSTEM SYSPLEX
iiiiiiiiiiiiiiiiiiiiii jjjj kkk sysname plexname
The FLAGS field contains information about how the host has configured the device and whether the host supports CUIR. The contents of FLAGS field is defined as follows:
•2000: The host/LPAR supports the automatic service notification through the distributed library notification attention.
•4000: The host/LPAR is grouped to the device.
•6000: The host/LPAR supports the automatic service notification and the host/LPAR is grouped to the device.
•8000: Device Explicitly Assigned by Host/LPAR.
•C000: The host/LPAR is grouped to the device and Device Explicitly Assigned by Host/LPAR.
•E000: The host/LPAR supports the automatic service notification and the host/LPAR is grouped to the device and Device Explicitly Assigned by Host/LPAR.
For more information, see the IBM TS7700 Series Control Unit Initiated Reconfiguration (CUIR) User’s Guide at:
LIBRARY DISPDRV,library-name
The existing LIBRARY DISPDRV,library-name command has been updated with a new field, CU, that was added to account for the new offline reason code for CUIR. The output for the command has the new syntax:
CBR1220I Tape drive status:
DRIVE DEVICE LIBRARY ON OFFREASN LM ICL ICL MOUNT
NUM TYPE NAME LI OP PT CU AV CATEGRY LOAD VOLUME
devnum devtyp libname b c d e f g hhhhhhh i mntvol
If a device is offline for CUIR reasons, the field contains a ‘Y’. Otherwise, it contains an ‘N’.
VARY device-number,ONLINE,RESET
Occasionally a device can be stuck offline for CUIR reasons. This situation can occur if, for example, the cluster that varied the device offline for CUIR reasons is no longer attached to the host. If the cluster is no longer attached, it cannot send the signal to the host to vary the device online. If this situation occurs, you must use this command to bring online the device that is being kept offline for CUIR reasons.
10.9 Return-to-scratch enhancement
When a volume is returned to scratch, there are two I/Os calls to the library for each volume:
•The I/O call to move the volume from private to scratch
•The I/O call to obtain the number of volumes in the scratch category
APAR OA48240 (z/OS V1R13+) can eliminate the second I/O call. After the APAR is applied, this change can be done with the LIBRARY DISABLE,CATCOUNT command. This change can decrease the overall duration of return-to-scratch processing. Re-enabling the second I/O call can be done with the LIBRARY RESET,CATCOUNT command.
Even though the second I/O call might be disabled, OAM is able to stay updated as to the current count of scratch tapes in the library through the use of a monitoring task in the OAM address space. This task queries the library for the current scratch count every 10 minutes. In addition, OAM continues to update the scratch count when a volume is changed from scratch to private.
10.10 Deleting Logical Volumes
When a logical volume has been moved from the insert category into a scratch or private category, it can no longer be deleted from the TS7700 MI. To delete these volumes, you must verify that a TCDB volume entry exists for the volume to be deleted, and verify that it is in scratch status. After these have been verified, you can use the EJECT function from a host that is connected to the TS7700. Because these volumes are logical, rather than being ejected by the host EJECT function, the logical volumes are deleted.
The following steps describe how to create the volume entry for the volume (if it is not already present in the TCDB), ALTER the volume to SCRATCH status, and EJECT the volume from the host using different methods:
1. Use the following JCL to invoke IDCAMS to create the volume entry in the TCDB:
//CREATVOL JOB ...
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
CREATE VOLUMEENTRY -
(NAME(Vxxxxxx) -
LIBRARYNAME(libname) -
MEDIATYPE(mediatype) -
LOCATION(LIBRARY)
2. Use ISMF to ALTER the use attribute from SCRATCH to SCRATCH. This command invokes the CBRUXCUA exit to communicate with the TMS. If the TMS indicates that the change is allowed to process, the category is changed in the library to the category defined for the corresponding media type in this host’s DEVSUPxx parmlib member.
3. Use one of the following methods to EJECT the tape:
a. Use the TMS to EJECT the volume. If RMM is used, the following command issues an EJECT for the volume:
RMM DV volser FORCE EJECT
b. Use ISMF to EJECT each volume.
c. Use the LIBRARY EJECT command.
d. Use the CBRXLCS macro to EJECT each volume.
e. Use the CBRSPLCS SAMPLIB member to EJECT each volume.
These steps can also be completed after a DR test if a DR host is shut down before deleting the logical volumes created during the DR test. These volumes continue to use space on the TS7700 until they are deleted.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.