OMEGAMON II
®
for SMS Data Interface
OMEGACENTER Gateway
™ for MVS
Version 340
GC32-9230-00
September 2002
Candle Corporation
201 North Douglas Street
Server, CT/DS, DELTAMON, eBA, eBA*ServiceMonitor, eBA*ServiceNetwork, eBusiness Assurance, eBusiness Institute, ETEWatch, IntelliWatch, IntelliWatch Pinnacle, MQSecure, MQView, OMEGACENTER, OMEGAMON, OMEGAMON/e, OMEGAMON II, OMEGAMON Monitoring Agent, OMEGAVIEW, OMEGAVIEW II, PQEdit, Solutions for Networked Applications, Solutions for Networked Businesses, and Transplex.
Trademarks and service marks of Candle Corporation: Alert Adapter, Alert Adapter Plus, Alert Emitter, AMS, Amsys, AutoBridge, AUTOMATED FACILITIES, Availability Management Systems, Candle Alert, Candle Business Partner Logo, Candle Command Center/SentinelManager, Candle CommandPro, Candle CIRCUIT, Candle eDelivery, CandleLight, CandleNet, CandleNet 2000, CandleNet eBP, CandleNet eBP Access, CandleNet eBP Administrator, CandleNet eBP Broker Access, CandleNet eBP Configuration, CandleNet eBP Connector, CandleNet eBP File Transfer, CandleNet eBP Host Connect, CandleNet eBP Object Access, CandleNet eBP Object Browser, CandleNet eBP Secure Access, CandleNet eBP Service Directory, CandleNet eBP Universal Connector, CandleNet eBP Workflow Access, CandleNet eBusiness Assurance, CandleNet eBusiness Exchange, CandleNet eBusiness Platform, CandleNet eBusiness Platform Administrator, CandleNet eBusiness Platform Connector, CandleNet eBusiness Platform Connectors, CandleNet eBusiness Platform Powered by Roma Technology, CandleNet eBusiness Platform Service Directory, CCC, CCP, CEBA, CECS, CICAT, CL/ENGINE, CL/GATEWAY, CL/TECHNOLOGY, CMS, CMW, Command & Control, Connect-Notes, Connect-Two, CSA ANALYZER, CT/ALS, CT/Application Logic Services, CT/DCS, CT/Distributed Computing Services, CT/Engine, CT/Implementation Services, CT/IX, CT/Workbench, CT/Workstation Server, CT/WS, !DB Logo, !DB/DASD,
!DB/EXPLAIN, !DB/MIGRATOR, !DB/QUICKCHANGE, !DB/QUICKCOMPARE, !DB/SMU, !DB/Tools, !DB/WORKBENCH, Design Network, DEXAN, e2e, eBAA, eBAAuditor, eBAN, eBANetwork, eBAAPractice, eBP, eBusiness Assurance Network, eBusiness at the speed of light, eBusiness at the speed of light logo, eBusiness Exchange, eBusiness Institute, eBX, End-to-End, ENTERPRISE, Enterprise Candle Command Center, Enterprise Candle Management Workstation, Enterprise Reporter Plus, EPILOG, ER+, ERPNet, ESRA, ETEWatch Customizer, HostBridge, InterFlow, Candle InterFlow, Lava Console, MessageMate, Messaging Mastered, Millennium Management Blueprint, MMNA, MQADMIN, MQEdit, MQEXPERT, MQMON, NBX, NetGlue, NetGlue Extra, NetMirror, NetScheduler, OMA, OMC Gateway, OMC Status Manager, OMEGACENTER Bridge, OMEGACENTER Gateway, OMEGACENTER Status Manager, OMEGAMON Management Center, OSM, PC COMPANION, Performance Pac, PowerQ, PQConfiguration, PQScope, Response Time Network, Roma, Roma Application Manager, Roma Broker, Roma BSP, Roma Connector, Roma Developer, Roma FS/A, Roma FS/Access, RomaNet, Roma Network, Roma Object Access, Roma Secure, Roma WF/Access, Roma Workflow Access, RTA, RTN, SentinelManager, Somerset, Somerset Systems, Status Monitor, The Millennium Alliance, The Millennium Alliance logo, The Millennium Management Network Alliance, TMA2000, Tracer, Unified Directory Services, Volcano and ZCopy. Trademarks and registered trademarks of other companies: AIX, DB2, MQSeries and WebSphere are registered trademarks of International Business Machines Corporation. SAP is a registered trademark and R/3 is a trademark of SAP AG. UNIX is a registered trademark in the U.S. and other countries, licensed exclusively through X/Open Company Ltd. HP-UX is a trademark of Hewlett-Packard Company. SunOS is a trademark of Sun Microsystems, Inc. All other company and product names used herein are trademarks or registered trademarks of their respective companies.
Copyright © August 2002, Candle Corporation, a California corporation. All rights reserved. International rights secured.
Threaded Environment for AS/400, Patent No. 5,504,898; Data Server with Data Probes Employing Predicate Tests in Rule Statements (Event Driven Sampling), Patent No. 5,615,359; MVS/ESA Message Transport System Using the XCF Coupling Facility, Patent No. 5,754,856; Intelligent Remote Agent for Computer Performance Monitoring, Patent No. 5,781,703; Data Server with Event Driven Sampling, Patent No. 5,809,238; Threaded Environment for Computer Systems Without Native Threading Support, Patent No. 5,835,763; Object Procedure Messaging Facility, Patent No. 5,848,234; End-to-End Response Time Measurement for Computer Programs, Patent No. 5,991,705; Communications on a Network, Patent Pending; Improved Message Queuing Based Network Computing Architecture, Patent Pending; User Interface for System Management Applications, Patent Pending.
NOTICE: This documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions set forth in the applicable license agreement and/or the applicable government rights clause.
This documentation contains confidential, proprietary information of Candle Corporation that is licensed for your internal use only. Any unauthorized use, duplication, or disclosure is unlawful.
Preface
. . . 7
Syntax Diagrams . . . .9
Documentation Conventions . . . .11
Adobe Portable Document Format . . . .13
What’s New in OG/MVS Version 340 . . . 15
Chapter 1.
Before You Begin . . . 19
What this OG/MVS Function Can Do For You . . . .20
The VU API. . . .21
VU API Environment. . . .23
IBM Storage Management Subsystem . . . .24
OMEGAMON II for SMS Data. . . .25
Candle Management Server . . . .26
Chapter 2.
VU API Components . . . 27
Logging On and Off . . . .28
LOGON . . . .29
LOGOFF . . . .31
VU Functions. . . .32
VU Templates . . . .34
OMEGAMON II for SMS Base Tables . . . .39
Chapter 3.
Putting It All Together . . . 43
Using the VU API . . . .44
Data Format Considerations . . . .45
LOGON to CMS . . . .46
Defragmenting DASD . . . .47
Migrating or Releasing Space on Non-SMS DASD. . . .50
Enabling Caching on a List of 3390 DASD Volumes . . . .55
Enabling Caching on Production 3390 DASD Volumes . . . .57
LOGOFF from Candle Management Server and Cleanup . . . .59
Chapter 4.
Installation and Customization . . . 61
Requirements for OMEGAMON II for SMS . . . .62
Security . . . .63
Adding the OG/MVS Loadlib to the CMS TKANMOD Concatenation . . . .64
Adding the VUSERVER pluapplid . . . .65
VUINSERT . . . .73 VUDELETE. . . .75 VUSUBST . . . .78 VUOPEN . . . .80 VUFETCH. . . .82 VUCLOSE. . . .85 VUDROP . . . .86
Reuse of Request Handles (REQHDLs) . . . .87
Redirecting the Output of VUFETCH. . . .88
Function Return Codes . . . .89
Chapter 6.
Syntax for Constructing a Search . . . 95
Comparison Considerations . . . .96 Data Constants . . . .97 Operators . . . .98 Substitution Symbols. . . .99 Expressions . . . .100 Predicates . . . .101 Predicate Evaluation . . . .102 Search Conditions . . . .104
Appendix A.
VU Templates . . . 105
Appendix B.
OMEGAMON II for SMS Base Tables. . . 137
ACTEFTRTAB. . . .139 ACTREQTAB . . . .141 ACTRESPTAB. . . .147 APPL . . . .148 CACHE_CU . . . .149 CACHE_DET . . . .151 CACHE_DEV . . . .156 CACHE_ENV . . . .158 CHAN_PATH . . . .159 DASD . . . .161 DASD_USERS . . . .165 DSN_ENQS . . . .166 DSN_IO_ST . . . .167 DSN_LOC. . . .169 DSN_SMS . . . .170 DSNS . . . .171 HSM_CDS . . . .175 HSM_DS_RV . . . .176 HSM_FUN_DA . . . .177
HSM_FUN_ST . . . .178 HSM_REQS . . . .180 HSM_STATUS. . . .182 HSM_STOR . . . .184 JOB . . . .186 LCU . . . .187 RMF_ENV . . . .189 SMS_CONFIG . . . .190 SMS_DAT_CL . . . .191 SMS_MAN_CL . . . .193 SMS_ST_CL . . . .195 SMS_ST_GRP. . . .196 SYSTEM_ENV . . . .198
Appendix C.
Identifying and Locating Messages . . . 199
Appendix D.
Guide to Candle Customer Support . . . 201
Base Maintenance Plan . . . .202
Enhanced Support Services . . . .206
Customer Support Contact Information. . . .207
Glossary
. . . 209
Preface
About this document
This document describes the OMEGAMON II
®for SMS Data Interface function of OG/MVS
®.
It contains all the information you need to install the function at your site and start using
OMEGAMON II for SMS data. This document contains:
n
a description of the function’s components
n
an explanation of the VU Application Programming Interface
n
a description of the OMEGAMON II for SMS Candle Management Server
® nscenarios demonstrating how to use the interface
The following manuals comprise the OG/MVS documentation set:
n
OG/MVS Configuration and Customization Guide
nOG/MVS User’s Guide
n
OG/MVS Command Reference Manual
n
OG/MVS OMEGAMON II for SMS Data Interface
nOG/MVS: Using the Subsystem Logging Facility
nCandle Product Messages Manual
For additional information on OMEGAMON II for SMS, consult the
OMEGAMON II for SMS
User’s Guide
.
Note:
To make use of the OG/MVS OMEGAMON II for SMS Data Interface, your
OMEGAMON II for SMS product must be at a level currently supported by Candle
Corporation.
n
technical documentation CD-ROM that came with your product
n
technical documentation information available on the Candle Web site at
www.candle.com
n
online help provided with this and the other related products.
Ordering additional documentation
To order additional product manuals, contact your Candle Customer Support
representative.
We would like to hear from you
Candle welcomes your comments and suggestions for changes or additions to the
documentation set. A user comment form, located at the back of each manual, provides
simple instructions for communicating with the Candle Information Development
department.
You can also send email to [email protected]. Please include "OMEGACENTER
Gateway for MVS OMEGAMON II for SMS Data Interface Version 340" in the subject
line.
Syntax Diagrams
Syntax Diagrams
This manual uses the format below to describe the syntax of the OG/MVS commands.
n
Some commands can be abbreviated. If an abbreviation is applicable, it is shown in
parentheses next to the command name.
n
Read the syntax diagrams from left to right, from top to bottom, following the path of the
line.
n
The symbol below indicates the statement is continued:
n
The symbol below indicates that a line is continued from the previous line:
nThe symbol below indicates the end of a statement:
n
Required items appear on the horizontal line (the main path).
nOptional items appear below the main path.
n
When you can choose from two or more items, they are stacked vertically.
If you must choose one of the items, the item at the top of the stack appears on the main
path.
If choosing one of the items is optional, the entire stack appears below the main path.
> > > < Required Item >< STATEMENT OPTIONAL ITEM >< STATEMENT Required Choice1 >< Required Choice2 STATEMENT Optional Choice1 >< STATEMENT
n
An arrow returning to the left above the main line indicates an item that can be repeated.
A repeat arrow above a stack indicates that you can make more than one choice from the
stacked items, or repeat a single choice.
n
If punctuation marks, parentheses, arithmetic operators, or other symbols are shown, they
must be entered as part of the syntax.
n
An operand name ending in
/s
specifies a choice of one or more of the operands, the
various choices separated by space(s). For example:
option/s
specifies
option1 option2 ...
n
An operand name ending in ,
s
specifies a choice of one or more of the operands, the
various choices separated by commas. For example:
pattern,s
specifies
pattern1,pattern2,...
Default operands are underlined.
STATEMENT ><
<
Documentation Conventions
Documentation Conventions
Introduction
Candle documentation adheres to accepted typographical conventions for command syntax.
Conventions specific to Candle documentation are discussed in the following sections.
Panels and figures
The panels and figures in this document are representations. Actual product panels may differ.
Required blanks
The slashed-b (
b
) character in examples represents a required blank. The following example
illustrates the location of two required blanks.
beBA*ServiceMonitorb0990221161551000
Revision bars
Revision bars (|) may appear in the left margin to identify new or updated material.
Variables and literals
In examples of command syntax, uppercase letters are actual values (literals) that the user
should type; lowercase letters are used for variables that represent data supplied by the user.
Default values are underscored.
LOGON APPLID (cccccccc)
In the above example, you type LOGON APPLID followed by an application identifier
(represented by
cccccccc
) within parentheses.
Symbols
The following symbols may appear in command syntax:
Table 1. Symbols in Command Syntax
Symbol Usage
| The “or” symbol is used to denote a choice. Either the argument on the left or the argument on the right may be used. Example:
YES | NO
In this example, YES or NO may be specified.
[ ] Denotes optional arguments. Those arguments not enclosed in square brackets are required. Example:
APPLDEST DEST [ALTDEST]
In this example, DEST is a required argument and ALTDEST is optional.
{ } Some documents use braces to denote required arguments, or to group arguments for clarity. Example:
COMPARE {workload}
-REPORT={SUMMARY | HISTOGRAM}
The workload variable is required. The REPORT keyword must be specified with a value of SUMMARY or HISTOGRAM.
_ Default values are underscored. Example:
COPY infile outfile - [COMPRESS={YES | NO}]
In this example, the COMPRESS keyword is optional. If specified, the only valid values are YES or NO. If omitted, the default is YES.
Adobe Portable Document Format
Adobe
Portable Document Format
Printing this book
Candle supplies documentation in the Adobe Portable Document Format (PDF). The Adobe
Acrobat Reader will print PDF documents with the fonts, formatting, and graphics in the
original document. To print a Candle document, do the following:
1.
Specify the print options for your system. From the Acrobat Reader Menu bar, select
File >
Page Setup…
and make your selections. A setting of 300 dpi is highly recommended as is
duplex printing if your printer supports this option.
2.
To start printing, select
File > Print...
on the Acrobat Reader Menu bar.
3.
On the Print pop-up, select one of the
Print Range
options for
n
All
n
Current page
n
Pages from: [ ] to: [ ]
4.
(Optional). Select the Shrink to Fit option if you need to fit oversize pages to the paper size
currently loaded on your printer.
Printing problems?
The print quality of your output is ultimately determined by your printer. Sometimes printing
problems can occur. If you experience printing problems, potential areas to check are:
n
settings for your printer and printer driver. (The dpi settings for both your driver and
printer should be the same. A setting of 300 dpi is recommended.)
n
the printer driver you are using. (You may need a different printer driver or the Universal
Printer driver from Adobe. This free printer driver is available at www.adobe.com.)
n
the halftone/graphics color adjustment for printing color on black and white printers (check
the printer properties under
Start > Settings > Printer
). For more information, see the
online help for the Acrobat Reader.
n
the amount of available memory in your printer. (Insufficient memory can cause a
document or graphics to fail to print.)
For additional information on printing problems, refer to the documentation for your printer
or contact your printer manufacturer.
Contacting Adobe
If additional information is needed about Adobe Acrobat Reader or printing problems, see
the Readme.pdf file that ships with Adobe Acrobat Reader or contact Adobe at
What’s New in OG/MVS
Version 340
This section provides a description of the new features that have been incorporated into
OG/MVS Version 340.
TCP/IP connectivity enhancements
TCP/IP communications have been simplified by permitting you to optionally remove the AF
packet header when communicating between OG/MVS and systems or applications that are
unable to comply with the Candle AF packet header protocol. You accomplish this by means
of a new option on the LINK DEFINE and COMM START commands. In addition, new
SEND and RECEIVE datatypes have been added to the COMSDRCV REXX function. You
must use the SEND and RECEIVE datatypes when you want to transfer data over a link
having the AF packet header turned off.
New keywords have been added to COMM START and COMM STOP commands. The
CONNECT_EXEC keyword on the COMM START command identifies a named exec that
runs whenever a connection to the server is established and is mandatory when you have
specified AFPACKET(OFF). The CID keyword on the COMM STOP command identifies a
particular connection to a server to be stopped.
A new COMADMIN REXX function provides GIVE and TAKE options that permit passing
ownership of a connection from one match to another.
Passing larger amounts of data on a TCP/IP match
You can now pass more data to an individual match. OG/MVS will permit passing a larger
amount of parameter data to a REXX procedure. In addition, it will provide the capability to
create a conversation between matches so that multiple 32K packets can be transferred. This
is accomplished by permitting the DATARPLY datatype to code the
replylength
keyword on
the COMSDRCV REXX function.
Automated peer-to-peer link management
By predefining link attributes, it is now possible to automatically establish connections at
OG/MVS startup. The following product changes support this function:
n
The optional RECOVERY keyword on the LINK DEFINE command indicates that an
INACTIVE link having a desired state of ACTIVE is to be automatically started when the
definition.
n
The new SCOPE keyword on the LINK START command specifies those links that are to
be selected for LINK START processing according to their activation state.
n
Two new startup parameters, HOSTNAME and LINKDEFS are added.
HOSTNAME(xxxxxxxx) overrides the default name of the trusted hostnames member in
RKANPAR. The LINKDEFS(xxxxxxxx) parameter overrides the default name of the link
definitions member in RKANPAR. During product startup, when TIMEOUT(nnn) is
specified on the LINKDEFS keyword, it specifies the amount of time to wait for the LINK
START command issued immediately after processing the LINKDEFS member to
complete before startup is allowed to continue.
Changes to the OPER command when RESP is specified
The OPER command issues an MVS or subsystem command. On this command, the RESP
parameter specifies that a set of line variables will receive the response text resulting from the
command. Additional parameters have been added to the OPER command when specified
with the RESP parameter:
n
TIMEOUT(pp,ss): The new ss value specifies the number of seconds (from 1 through
3600) that OG/MVS is to wait for each response message line from a multi-line write to
operator before assuming the response is complete.
n
MAXLINES(nnnn): This new parameter specifies that a response is to be deemed
complete when the specified number of lines is received.
n
ENDMSG(prefix): This new parameter specifies that the response is to be deemed
complete when the specified prefix is encountered in one of the response lines.
The ss value is also added to the OPERRESP OG/MVS startup parameter.
In addition, the CMDSDRCV function has been modified such that when it causes an OPER
command with RESP specified to be executed on a remote system, it also causes an AOCASE
variable to be built when the reply from the remote system is received.
Additional modifications
n
New global variables have been added for COM matches.
n
A DUB_AS_PROCESS command, having the same function as the OG/MVS startup
parameter of the same name, has been provided.
Storage Constraint Relief
The amount of storage constraint relief realized will vary depending on OG startup
parameters and will be equal to (MAXMAT - MAXRUN) * 480 bytes.
Online documentation
With Version 340, Candle Corporation has moved AF/OPERATOR manuals from IBM
BookMaster to Adobe FrameMaker. This move was made to better enable us to address our
customers’ needs by providing tools that enhance productivity.
One of the results of the move is that it is no longer possible to create BookManager versions
of the AF/OPERATOR manuals. However, the manuals remain available online in the Adobe
PDF version on CD-ROM and are also available on the Candle Corporation website at
www.Candle.com
.
The documentation CD being provided with this release has robust and easy-to-use search
capabilities. You can search for information in
multiple volumes, multiple versions, and across
products. The CD also provides easy setup of search indexes with a single click of the mouse.
If you want to order printed copies of the documentation, please contact your Candle
Support Services representative.
Enhancements to product documentation
n
Additional documentation about obtaining SMF data has been added to the
OG/MVS
User’s Guide
.
n
Additional documentation about using the Probe Directive, Probe Input, and Misc. Parms
Before You Begin
Introduction
The OG/MVS OMEGAMON II for SMS Data Interface function adds the VU Application
Programming Interface (VU API), a bidirectional interface, to one or more OMEGAMON II for
SMS products. The VU API enables OG/MVS to query and manipulate data collected by
OMEGAMON II for SMS, to pass this statistical information on to other applications, and to
execute actions on a storage system.
This function is intended to support your implementation of system managed storage for
managing and controlling your enterprise’s storage resources.
Chapter Contents
What this OG/MVS Function Can Do For You . . . 20
The VU API . . . 21
VU API Environment . . . 23
IBM Storage Management Subsystem. . . 24
OMEGAMON II for SMS Data . . . 25
Candle Management Server . . . 26
What this OG/MVS Function Can Do For You
Introduction
The OMEGACENTER Gateway for MVS VU API enables you to automate DASD
management tasks. You can, for example, have an automation REXX exec to
n
query the fragmentation index of DASD volumes and submit batch jobs to defragment
those with a high fragmentation index
n
monitor non-SMS-managed DASD volumes, to determine when free space can be
reclaimed, and initiate free space release or HSM dataset migration
n
search for production 3390 DASD volumes with disabled caching and enable caching on
all volumes or on selected volumes
Audience
This function is intended for system programmers, storage administrators, data center
personnel, and others who are responsible for implementing automation procedures for
DASD administration, recoverability, availability, and performance management.
What you need to know
You must be familiar with these Candle products:
n
The current version of OG/MVS
n
The current version of OMEGAMON II for SMS
You will also need a working knowledge of REXX programming language. For information on
REXX, consult the following IBM manuals:
n
TSO Extensions Version 2 REXX Ref
erence
nTSO/E REXX/MVS Reference
The VU API
The VU API
Introduction to the VU API
The VU Application Programming Interface (VU API) is a synchronous communications
interface. It establishes a VTAM
®connection between OG/MVS and OMEGAMON II for
SMS, making OG/MVS a client of the Candle Management Server™ (CMS™) facility.
The VU API consists of the following components:
n
Extensions to the LOGON and LOGOFF commands
nREXX function package
n
VU Templates
n
TKANSAM (samples)
Commands
This function modifies two OG/MVS commands:
n
AF LOGON
nAF LOGOFF
These commands establish and terminate LU0 sessions with CMS.
REXX function package
The REXX function package is a set of 8 REXX callable functions which provide an
application programming interface for automation procedures running in the OG/MVS
address space.
For a complete description of each VU function, see
“VU API Components” on page 27
.
Function Description
VUQUERY() Compiles a query request. VUINSERT() Compiles an insert request. VUDELETE() Compiles a delete request.
VUSUBST() Substitutes symbols into compiled requests. VUOPEN() Executes a request.
VUFETCH() Retrieves one or more rows of a table. VUCLOSE() Closes an active request.
VU Templates
VU Templates are Candle supplied views that generate predefined requests used in query,
insert, and delete operations. Each VU Template specifies a
view
of the CMS base tables. A
view
defines the tables, columns, and rows that the client application needs. A VU Template
can retrieve all or a subset of the columns contained in one or more CMS base tables.
TKANSAM
TKANSAM contains sample REXX programs designed to carry out specific storage
management tasks. TKANSAM programs are not intended for you to use in their present
state. Candle has provided them as models you can refer to while writing your own REXX
execs. If you want to use one of these programs, you will need to customize it to suit your
environment.
VU API Environment
VU API Environment
System Managed Storage
The VU API is intended for your automated storage management environment. You use
Candle’s OMEGAMON II for SMS and the IBM Storage Management Subystem to monitor,
control, and automate storage systems across your enterprise. You may have additional
Candle Availability Management Systems products installed.
Diagram of the VU API operating environment
This figure illustrates the relationship between the VU API, OG/MVS, and SMS in your
enterprise.
Components
The basic operating environment for the VU Application Programming Interface consists of
these components:
n
OG/MVS
n
OMEGAMON II for SMS
nCandle Management Server
IBM Storage Management Subsystem
Introduction
The IBM Storage Management Subsystem (SMS) automates storage management. SMS gives
the storage administrator the ability to centralize, automate, and prioritize storage allocation
by the performance characteristics of the storage media. SMS does not provide realtime
storage data.
SMS components
SMS consists of hardware and software components. The SMS hardware components are
n
cache control units
nDASD
n
Optical storage devices
The SMS software components are:
Component Description
DFSMSdfp™ An IBM data facility product that provides storage, data, program, and device management functions.
DFSMSdss™ A dataset services product that provides data movement, copy, dump, and space management functions.
DFSMShsm™ A hierarchical storage manager that provides backup, recovery, migration, and space management functions.
DFSMSrmm™ A removable media manager that provides management functions for removable media such as tape cartridges, reels, and optical volumes.
OMEGAMON II for SMS Data
OMEGAMON II for SMS Data
Introduction
OMEGAMON II for SMS is Candle’s realtime performance monitor for your storage
resources. It provides status indicators, data displays, and built-in action capabilities.
OMEGAMON presents a high-level overview of the status of your storage resources through
the Storage Management Status Overview panel.
OMEGAMON II for SMS consists of the following components:
n
application address space
n
Candle Management Server (data collection address space)
nCandle Subsystem
What data OMEGAMON collects
OMEGAMON II for SMS uses data collection programs, probes, that execute in the data
collection address space. Probes collect information on:
n
Channel Path
nLogical Control Unit
nCache Control Unit
nSMS storage groups
n
user-defined storage groups
ndatasets
n
applications
n
Data Facility Hierarchical Storage Manager (DFHSM or HSM)
OMEGAMON II for SMS manages DASD device statistics and dataset I/O statistics with its
Candle Management Server facility.
Candle Management Server
Introduction
The Candle Management Server (CMS) is a data collector that runs in its own address space
and collects, manages, and distributes data for OMEGAMON II for SMS. It stores the
statistical information the probes gather in rectangular data structures (tables, columns, and
rows). CMS allows multiple host queries from a single point. You can send a query to every
CMS on your system and receive data back in one homogeneous table.
The VU API provides direct access to the data managed by Candle Management Server. This
gives you the ability to query, update, insert, and delete data in CMS tables.
The CMS facility consists of the:
n
CMS Catalog
nbase tables
n
Application Programming Interface
Candle Management Server Catalog
The CMS Catalog is the functional equivalent of the data dictionary for a database
management system. The Catalog contains definitions of CMS objects (base tables, columns,
request handles, views, and applications) and information on their interrelationship. No data
can be queried or manipulated unless it is defined in the CMS catalog.
Candle Management Server base tables
Base tables
are the rectangular data structures in which OMEGAMON II for SMS stores
information. A table is a logical structure of data element values arranged in rows of column
values. A table column represents one attribute of a data object (for example, I/Os per second
for a volser on a specific DASD volume). Every column has a unique name identifying its
data type. A table row represents an occurence of the data (for example, 0.8 for I/Os per
second). Rows do not have names. The number of rows indicates how many times the table
data occurs. In a realtime server, the number of rows a table contains is unpredictable; they
may vary widely over a few milliseconds.
A set of predefined OMEGAMON II for SMS probes build each CMS table. The structure of
the base tables is fixed (See
“OMEGAMON II for SMS Base Tables” on page 137
). To
understand the data returned from a query to CMS, you must know the design of the
individual base tables.
VU API Components
Introduction
This chapter describes the components needed for a successful data query and manipulation.
In
“Putting It All Together” on page 43
, the scenarios will demonstrate how you can use these
components to
1. log on to CMS
2. use the VU functions within the framework of various VU templates to acquire data from
base tables
3. log off
Contents
Logging On and Off . . . 28
LOGON . . . 29
LOGOFF . . . 31
VU Functions . . . 32
VU Templates . . . 34
OMEGAMON II for SMS Base Tables . . . 39
Logging On and Off
Introduction
The VU API is implemented through extensions to the LOGON and LOGOFF AFHOST
environment commands and by a REXX function package. This section describes the
LOGON and LOGOFF commands. Other components of the REXX function package are
discussed in
“VU Functions” on page 32
.
Modifications
The LOGON and LOGOFF commands have been modified to establish and terminate LU0
sessions to a VU server dialog defined in the CMS address space where OMEGAMON II for
SMS probes are installed. The VU server dialog dispatches a process after a successful
LOGON.
LOGON
LOGON
Introduction
LOGON initiates an LU0 session with the VU server dialog that resides in the CMS address
space used by OMEGAMON II for SMS for data collection.
Syntax
The following parameters have modified meanings for this enhancement. Ignore all other
options when establishing a VU API session.
appltype The type of VTAM application. Enter CTDS to establish a VU API session.
APPLID(applid)
The APPLID of the VTAM application. When you define CMS as the appltype, applid specifies the VTAM LU0 APPLID of the VU server dialog that runs the CMS address space used by OMEGAMON II for SMS for data collection.
Note: This applid must be identical to the pluapplid specified with the START command in member KDSCNFG. See
“Adding the VUSERVER pluapplid”
on page 65
.NAME(applname)
A user-defined name assigned to the LU0 session. When specified during a successful logon, it is passed as an argument to subsequent VU API function calls.
TRACE If specified, enables diagnostic messages.
USERID(userid/password)
The user ID and password required to validate access to CMS. The password appears as asterisks in the system log. A CMS session requires a user ID and password combination that is known to the security system installed in the CMS
LOGON appltype APPLID(applid) NAME(applname)
Options: DATA(text) INTERVAL(time) LTERM(luid) PASSWORD(password) SSIZE(n) TRACE USERID(userid/password) >< option(s)
Return Codes
Comments
n
The LOGON command is often issued by a startup REXX exec.
n
The maximum logon time default is 20 seconds, unless overridden by the LOGONTLM
startup option. The range available is 1 to 99 seconds. See the
AF/OPERATOR
Configuration and Customization Guide
for more information.
Examples
You must establish a session between the CMS address space and OMEGAMON II for SMS’s
address space (data collection) before you make a data query or request.
Following is an example of the LOGON command in a REXX exec used to log onto a CMS
session through the VTAM APPL RGOGVU00. OG/MVS supplies the CT/Engine™ external
security system with the user ID CANUSER and the user password CANPSWD. The
connection name, OMIISMS, is used to identify the communications session.
ADDRESS AFHOST “LOGON CTDS APPLID(RGOGVU00)”,
“NAME(OMIISMS) USERID(CANUSER/CANPSWD)” status=rc
IF status<>0 THEN SAY “LOGON TO APPLID(RGOGVU00) FAILED”
Note:
You can establish multiple sessions to multiple address spaces or to the same CMS
address space.
All examples shown in
“Putting It All Together” on page 43
reuse the same connection
created by this example.
Return
Code Reason
0 VTAM session successfully established.
16 Invalid syntax.
LOGOFF
LOGOFF
Introduction
LOGOFF terminates an LU0 session with the VU server dialog that resides in the CMS
address space used by OMEGAMON II for SMS for data collection.
Syntax
Return Codes
Examples
Terminate a session with the data collection address space by issuing the LOGOFF
command.
This is an example of the LOGOFF command in a REXX exec used to log off of a CMS
session through the VTAM APPL OMIISMS:
ADDRESS AFHOST “LOGOFF OMIISMS” status=rc
IF status<>0 THEN DO
SAY “LOGOFF FROM APPLID(RGOGVU00) FAILED” END
Any outstanding queries or data manipulation requests are closed and dropped automatically
with an error following successful logoff processing. Action requests submitted to OMIISMS
continue to execute.
name The name (applname) assigned to the LU0 session by the NAME operand in the LOGON command that initiated the session.This operand is required. Any active requests are closed and dropped before logoff processing completes.
Return Code Reason
0 VTAM session successfully terminated.
16 Invalid syntax.
Non-zero Logoff failed.
VU Functions
Introduction
The REXX function package is a set of REXX callable functions that provides an application
programming interface for automation procedures running in the OG/MVS address space.
The API is supported
only
for REXX execs that execute within the OG/MVS address space.
Process
The VU function process is as follows:
1. LOGON establishes a session to the CMS address space.
2. The name of the session is then passed to the VUQUERY, VUINSERT, or VUDELETE
function in order to compile a query, insert, or delete request. Compilation of requests
allows reuse of requests without recompiling and minimizes the resources required to
interpret the request.
3. Compiled requests can be of more general use by introducing
substitution symbols
that
allow values to be assigned
after
compilation. You must substitute values before you use
VUOPEN to execute a request by a call to the VUSUBST function.
4. CMS allows the query and manipulation of data similar to that of a relational database
management system. Compiled requests are executed by calling the VUOPEN function.
When you execute VUOPEN, the data collected for a query is assembled into a result
table.
5. After a successful query, you can fetch the rows in the result table by calling the
VUFETCH function.
6. When request processing is completed, and all rows have been fetched for queries, you
can call the VUCLOSE function to release resources occupied by the result table, if any.
7. Additional calls to VUSUBST and VUOPEN can be issued after VUCLOSE is issued to
re-execute a request without recompiling.
8. A call to the VUDROP function releases resources occupied by a compiled request. Once
VUDROP is executed, the dropped request is no longer valid for any subsequent VU API
function calls.
9. LOGOFF terminates the session with the CMS address space. All compiled requests,
result tables, and associated resources are automatically released during the logoff.
VU Functions
Function sequence
The following table shows the normal processing sequence of VU API service calls.
Complete descriptions of each function are provided in
“VU Functions” on page 69
.
API Command or Function
Prerequisite Description
LOGON command Active SLU APPLID Establish LU0 session to CMS. VUQUERY(),
VUINSERT(), or VUDELETE() functions
LOGON Compile and create CMS request.
VUSUBST() function VUQUERY(), VUINSERT(), or VUDELETE() function
Substitute values into compiled statement before execution.
VUOPEN() function VUQUERY(), VUINSERT(), or VUDELETE() function
Execute a request.
VUFETCH() function VUOPEN() Retrieve one or more rows of result table. VUCLOSE() function VUOPEN() Close an active request.
VUDROP() function VUQUERY(), VUINSERT(), or VUDELETE() function
Destroy a compiled request. If the request to be dropped is not yet closed, a VUCLOSE will be issued before the request is dropped to ensure integrity of insert, delete, or update requests.
LOGOFF command LOGON Terminate LU0 session with CMS. Any outstanding requests are automatically closed and dropped as a result of the session termination.
VU Templates
Introduction
VU Templates generate predefined queries and data management requests used by the
VUQUERY, VUINSERT, and VUDELETE functions. Each VU Template defines the
following:
n
base table name or names
n
column names of the base table(s)
nsearch criteria
VU Template naming convention
VU Template names begin with the letters DF, the Candle product identifier for OMEGAMON
II for SMS.
Modifying views
A view associates a table with a list of columns and a filter (which identifies specific rows of
the table). You cannot add to the tables or columns defined in a view, but you can narrow a
view’s focus to fetch only the data required by an application. You can modify a view
definition to
n
select a subset of the column data
n
rearrange the order of the columns fetched
n
retrieve only a subset of rows by adding to the search criteria
To modify the columns and rows selected by a view, use the list of column names and search
criteria arguments. The list of column names specifies the columns to be retrieved. The search
criteria optional argument specifies the rows to be retrieved.
Using a list of column names
Use the VUQUERY list of column names argument to specify the list of columns. The
argument is a character string specifying a subset of the desired columns. The column names
must be separated by commas and must be a subset of the column names identified by the
VU Template.
You can rearrange the order of columns fetched by a query or exclude unnecessary columns
to improve data collection performance. See
“VUQUERY” on page 70
for additional
information.
VU Templates
Using search criteria
Use the VUQUERY and VUDELETE optional search criteria argument to determine the rows
fetched or deleted. The criteria you specify is logically ANDed to the search criteria specified
by the VU Template. This option enables you to make more selective query and delete
operations.
Search criteria may contain substitution symbols that allow a VU Template to be reused
without being recompiled. Substitution symbols appear as “?” in the search criteria
arguments. See
“VUQUERY” on page 70
and
“VUDELETE” on page 75
for additional
information.
Joined tables
VU Templates that refer to more than one base table are created by
joining
the tables by one
or more common column values. You can only query VU Templates of joined tables; you
cannot insert or delete rows. All VU Templates for joined tables are applicable only to
VUQUERY function calls.
Template descriptions
The following table lists the names of the VU Templates included in the VU API, the page in
“VU Templates” on page 105
where a detailed description of each template can be found, the
function it performs, and a description of information that the view contains.
VU Template Name Page Valid
Operations
VU Template Description
DF.ACTION page 107 VUQUERY List of all the DASD volume and dataset actions available from OMIISMS. DF.ACTIONREQ page 107 VUQUERY,
VUINSERT, VUDELETE
Access and manipulate action requests issued by OMIISMS. Queries return action request status. Inserts submit new action requests. Deletes cancel pending requests or remove completed action requests.
DF.ACTIONRESP page 109 VUQUERY Responses issued by completed action requests.
DF.ACTIVEJOB page 109 VUQUERY Current active jobs in the system. DF.CACHECU page 110 VUQUERY Cache control unit status and
performance.
DF.CACHEDETAIL page 111 VUQUERY Detailed cached DASD device performance statistics.
DF.CACHEDEVICE page 112 VUQUERY Cached DASD device performance statistics.
DF.DASD page 113 VUQUERY Direct Access Storage Devices. DF.DASDCACHE page 114 VUQUERY List DASD volume and cache
performance data for all online DASD volumes.
DF.DASDCACHEBYJOBNAME page 115 VUQUERY List DASD volume and cache
performance data for all volumes being accessed by a specific address space. DF.DASDCACHEDETAIL page 116 VUQUERY List DASD volume and detailed cached
performance data for all online DASD volumes.
DF.DASDUSER page 117 VUQUERY List of address spaces and datasets being accessed on a specific DASD volume. DF.DSBYASID page 117 VUQUERY List of all datasets being accessed by a
specific address space, given its address space ID.
DF.DSBYDSNAME page 118 VUQUERY DSCB and space information for each occurrence of a specific cataloged dataset on 1 or more (multiple) volumes. DF.DSBYJOBNAME page 118 VUQUERY Datasets accessed by a specific address
space by JOBNAME.
DF.DSBYVOLUME page 118 VUQUERY DSCB and space information for all datasets on a volume.
DF.DSENQ page 119 VUQUERY List of jobnames and ENQs for a specified dataset name.
DF.DSIOBYDSNAME page 120 VUQUERY Data set I/O and cache performance statistics by dataset name.
DF.DSIOBYJOBNAME page 121 VUQUERY Dataset I/O and cache performance statistics by job name.
DF.DSIOBYVOLUME page 121 VUQUERY Dataset I/O and cache performance statistics by volume.
DF.DSLOC page 122 VUQUERY VOLSER and device number for a specified dataset name.
DF.DSSMS page 122 VUQUERY SMS information for a specific dataset. DF.HSMCDS page 122 VUQUERY Space utilization information for HSM
control datasets.
DF.HSMDSRV page 123 VUQUERY HSM recovery versions for a specified dataset. One row for each backup version is available for recovery.
VU Template Name Page Valid
Operations
VU Templates
DF.HSMFUNDA page 123 VUQUERY Processing statistics for major HSM functions within the current HSM processing interval.
DF.HSMFUNST page 124 VUQUERY Hold status and activity status for major functions within HSM.
DF.HSMREQ page 124 VUQUERY, VUDELETE
Active and queued HSM request processing information.
DF.HSMSTATUS page 125 VUQUERY Status and activity information for HSM collected within the current HSM processing interval.
DF.HSMSTORAGE page 125 VUQUERY Status of virtual storage in the HSM address space.
DF.LCU page 126 VUQUERY Logical control unit information from RMF.
DF.LCUIORATE page 126 VUQUERY Logical control unit information from RMF with total DASD I/O rate.
DF.RMFENV page 127 VUQUERY Information about the RMF environment (collection interval) for the current MVS system.
DF.SMSCONFIG page 128 VUQUERY SMS base configuration data. DF.SMSDATACLASS page 128 VUQUERY SMS data class information.
DF.SMSDSBYDSNAME page 129 VUQUERY SMS managed dataset attributes with SMS classes.
DF.SMSDSBYVOLUME page 130 VUQUERY List of detailed information for an SMS managed dataset, given the DASD volume serial number.
DF.SMSDSIOBYJOBNAME page 131 VUQUERY Allows comparison of dataset I/O statistics with SMS storage class objectives for all datasets accessed by a specific address space.
DF.SMSDSIOBYVOLUME page 132 VUQUERY Allows comparison of dataset I/O statistics with SMS storage class objectives for all datasets on a specific SMS managed DASD volume.
DF.SMSMANAGEMENTCLASS page 133 VUQUERY SMS management class information. DF.SMSSTORAGECLASS page 133 VUQUERY SMS storage class information. DF.SMSSTORAGEGROUP page 134 VUQUERY SMS storage group information.
VU Template Name Page Valid
Operations
DF.VOLUMEBYJOBNAME page 135 VUQUERY DASD volumes being accessed by a specific active address space, given its jobname.
VU Template Name Page Valid
Operations
OMEGAMON II for SMS Base Tables
OMEGAMON II for SMS Base Tables
Introduction
This section describes the OMEGAMON II for SMS base tables currently defined in the CMS
catalog.
Matching formats
When you use the VUFETCH function call to retrieve rows of data returned by a query
request, you must be aware that the format of the values in the variables depends on the
format of the base table columns as specified in this section. Any comparison of values
specified in VUINSERT, VUSUBST, VUQUERY, or VUDELETE function calls requires you to
match exactly the specific column format.
CHAR and VARCHAR type columns are returned as character strings in REXX stem
variables. Other values may require scaling:
n
INTEGER columns are returned in numeric decimal format. Some numeric values
include fractional values that have been scaled into integers by multiplying them by a
factor of 10 or by clock milliseconds.
n
BITSTRING columns are returned as character strings. You can compare them to
hexadecimal literals in REXX execs (for example, ‘02’x, ‘00 FF 1A’x) or you can convert
them from character format to decimal numerics using the C2D standard REXX function.
Description
The following table describes the base tables supported by this enhancement. Valid
operations for the base tables listed are:
ACTREQTAB Query, insert, delete
HSM_REQS Query, delete
All other base tables Query
Base Table Name Page Table Description
ACTEFTRTAB page 139 Action Effector Table. List of all actions that can be inserted into the ACTREQTAB Table.
ACTREQTAB page 141 Action Request Table. Asynchronous DFDSS and DFHSM action requests used for SMS Services.
ACTRESPTAB page 147 Action Response Table. Responses issued by completed action requests (for SMS Services).
CACHE_CU page 149 Cache Control Unit Table. Cache control unit status and performance for each Control Unit.
CACHE_DET page 151 Cached Device Details Table. Cache performance by volser and device number.
CACHE_DEV page 156 Cached Device Table.
CACHE_ENV page 158 Cache Collection Environment Table. Cache collection interval information.
CHAN_PATH page 159 Channel Path Table. Channel path information by CHPID. DASD page 161 DASD Table. Direct Access Storage Device data by VOLSER,
UCB address, and device number.
DASD_USERS page 165 DASD Users Volume Table. List of jobnames and dataset names for a specified volser and device number.
DSN_ENQS page 166 Dataset Users Table. List of jobnames and ENQs for a specified dataset name.
DSN_IO_ST page 167 Dataset I/O Statistics Table. Dataset I/O and cache performance statistics by volser, device number, dataset name, and jobname. DSN_LOC page 169 Dataset Cataloged Volser Table. Volser and device number for
a specified dataset name.
DSN_SMS page 170 Dataset SMS Table. SMS information for a specific dataset. DSNS page 171 DSCB/Space Information Table. DSCB and space information
for one of the following:
n all datasets on a volume
n a specific data set on a specific volume
n each occurrence of a specific cataloged dataset on 1 or
more (multiple) volumes
HSM_CDS page 175 HSM Space Utilization Table. Space utilization information for HSM control datasets.
HSM_DS_RV page 176 HSM Recovery Table. HSM recovery versions for a specified dataset. One row for each backup version is available for recovery.
HSM_FUN_DA page 177 HSM Function Data Table. Processing statistics for major HSM functions within the current HSM processing interval.
HSM_FUN_ST page 178 HSM Function Status Table. Hold and activity statuses for major functions within HSM.
HSM_REQS page 180 HSM Request Data Table. Active and queued HSM request processing information.
HSM_STATUS page 182 HSM Status Table. Status and activity information for HSM collected within the current HSM processing interval. HSM_STOR page 184 HSM Address Space Virtual Storage Utilization Table. JOB page 186 Active Job Table. Current active jobs in the system.
OMEGAMON II for SMS Base Tables
RMF_ENV page 189 RMF Environment Table. Information about the RMF environment (collection interval) for the current MVS system. SMS_CONFIG page 190 SMS Base Configuration Data Table.
SMS_DAT_CL page 191 SMS Data Class Data Table.
SMS_MAN_CL page 193 SMS Management Class Data Table. SMS_ST_CL page 195 SMS Storage Class Data Table. SMS_ST_GRP page 196 SMS Storage Group Data Table.
SYSTEM_ENV page 198 System Environment Table. MVS and DFP environment information.
Putting It All Together
Introduction
This chapter explains how to use the VU API. It covers the process for creating a REXX exec
using VU Templates and the VU function package. Included are 6 usage scenarios that show
how to use the VU API to carry out specific storage management tasks.
n
logging on to Candle Management Server
ndefragmenting DASD
n
migrating or releasing space on Non-SMS DASD
nenabling caching on a list of 3390 DASD
n
ensuring that caching is enabled on production 3390 DASD
nlogging off of Candle Management Server and cleanup
This chapter also gives information on the scaling and format of CMS data.
Chapter Contents
Using the VU API . . . 44
Data Format Considerations . . . 45
LOGON to CMS . . . 46
Defragmenting DASD . . . 47
Migrating or Releasing Space on Non-SMS DASD . . . 50
Enabling Caching on a List of 3390 DASD Volumes. . . 55
Enabling Caching on Production 3390 DASD Volumes . . . 57
LOGOFF from Candle Management Server and Cleanup . . . 59
Using the VU API
Introduction
This section describes the steps in the process of writing and executing a REXX exec using the
VU API. It explains how the VU API communicates with the Candle Management Server.
Using TKANSAM
The REXX execs used in the scenarios in this chapter can be found in TKANSAM. The
TKANSAM programs are not intended for you to use in their present state. They are provided
as models that you can refer to while writing your own REXX execs. If you want to use one of
these programs, you will need to customize it to suit your systems.
Security
Security access to the VU API is verified when a LOGON command is issued to establish an
LU0 connection between OG/MVS and CMS. See
“Security” on page 63
for more
information.
Design process
This list gives the stages in the process for using the VU API to request data from or insert data
into Candle Management Server tables.
1.
Begin by reviewing the VU Templates to determine what information they retrieve from
Candle Management Server.
2.
Select the template or templates that will retrieve the information you require.
3.
Decide on overrides for columns and search criteria if necessary.
4.
Select a VU function that will accomplish the action required.
5.
Include the VU Template name, column names, and search criteria as arguments for the
function.
6.
Using one of the scenarios as a model, write a REXX program that includes the VU Template
and the VU function.
7.
Enter the LOGON command to establish an LU0 session with OMEGAMON II for SMS.
8.
Execute the REXX exec you have created.
Program Description
KOGVUX00 LOGON to Candle Management Server. KOGVUX0 Deframent DASD with high FRAGINDEX. KOGVUX0 Migrate or release space on non-SMS DASD. KOGVUX0 Enable caching on a list of 3390 DASD.
KOGVUX04 Ensure that caching is enabled on all production 3390 DASD volumes. KOGVUX99 LOGOFF from Candle Management Server.
Data Format Considerations
Data Format Considerations
Introduction
The format of the values returned by VUFETCH depends on the format of the base table
columns. Because of the way Candle Management Server stores character and integer data,
you will need to refer to the CMS base table descriptions to determine the column formats
and the range of values.
CHAR and VARCHAR columns
CHAR and VARCHAR type columns are returned as character strings in REXX stem
variables.
BITSTRING columns
BITSTRING columns are returned in character strings. These may be compared to hex literals
in REXX execs or can be converted from character format into decimal numerals using the
C2D standard REXX function.
Integer data scaling
INTEGER columns are returned in numeric decimal format. Some numeric values include
fractional values that are scaled into integers by multiplying them by a factor of 10 or by clock
milliseconds. You must determine the scaling factor for numeric values returned by
VUFETCH. Check the descriptions of each integer column in the base tables to determine
the scaling factor, if any.
For example, in the LCU table (
page 187
) the value in column ALL_CP_BSY is per cent (%)
multiplied by 1000. The value in column PCT_CUBUSY of the same table is % multiplied by
10. In comparison operations, the scaling and format of the values being compared must
match.
See
“Syntax for Constructing a Search” on page 95
for additional information about
formatting.
LOGON to CMS
Introduction
The following example shows a typical LOGON command. All scenarios that follow reuse the
same connection created by this example. See
“Logging On and Off” on page 28
for more
information about the LOGON command.
Example KOGVUX00
The line numbers in the following scenario are for reference purposes only.
Usage notes
n
Logon from OG/MVS to OMEGAMON II for SMS using the application type CTDS. See
“LOGON” on page 29
for details. In this example, TOD Trap KOGVUX04 periodically
executes REXX exec KOGVUX04, which searches for production 3390 DASD volumes
with caching disabled. This exec is decribed in
“Example KOGVUX04” on page 57
.
n
The
pluapplid
for the CMS address space is RGOGVU00.
000001 /* REXX */ 000002 applid=”RGOGVU00”
000003 ADDRESS AFHOST “LOGON CTDS APPLID(RGOGVU00)”,
000004 “NAME(OMIISMS) USERID(CANUSER/CANPSWD)” 000005 status=rc
000006
000007 IF status<>0 THEN SAY “LOGON TO APPLID(RGOGVU00) FAILED” 000008 ELSE DO
000009 /* Initialize TOD TRAP for Scenario 4 for every 5 minutes */ 000010 ADDRESS AFHOST “TRAP ADD(KOGVUX04) TOD(*) INTERVAL(00:05:00)”, 000011 “ENABLE ACTION(‘EX KOGVUX04’)”
000012 END
Defragmenting DASD
Defragmenting DASD
Introduction
This scenario shows how an automation REXX exec can be used to query the fragmentation
index of DASD volumes so that batch jobs to defragment these volumes can be submitted.
Selective defragmentation minimizes the dedicated maintenance time required to defragment
DASD by limiting processing to only those volumes requiring attention.
The defragmentation procedure can be customized with OG/MVS options to select different
groups of volumes on different days of the week.
Defragmentation policy
Example KOGVUX01
The line numbers in the following scenario are for reference purposes only.
This example shows all calls associated with a query.
000001 /* REXX */ 000002 status=VUQUERY(“OMIISMS”, “reqhdl”,, 000003 “DF.DASD”,, 000005 “VOLSER, DEV_TYPE”,, 000006 “FRAG_IDX > 800”) 000007
000008 IF status<>0 THEN SAY “VUQUERY error. status =” status 000009 ELSE DO
000010 /* VUQUERY was successful. Run Query */ 000011 status=VUOPEN(reqhdl)
000012 IF status<>0 THEN SAY “VUOPEN error. status =”status 000013 ELSE DO
000014 /* VUOPEN was successful, Fetch Data */ 000015 volser.0=0
000016 status=VUFETCH(reqhdl, “*”, “volser., dev_type.”) 000017 IF status<>0 THEN SAY “VUFETCH error. status =”status 000018 /* Close request */
000019 closestatus=VUCLOSE(reqhdl)
000020 IF closestatus<>0 THEN SAY “VUCLOSE error. status =” closestatus 000021 END
000022 dropstatus=VUDROP(reqhdl)
000023 IF dropstatus<>0 THEN SAY “VUDROP error. status =” dropstatus 000024 END
000025
000026 IF status=0 THEN DO
000027 /* VUFETCH was successful and one or more volumes were selected.*/ 000028 /* Submit a batch job to defragment each volume selected. */ 000029 DO i=1 to volser.0
000030 /* Call external function to format and submit a batch job to */ 000031 /* defragment the volume with a target fragmentation index(500)*/ 000032 IF dev_type.i=’0E’x THEN unit=”3380”
000033 ELSE IF dev_type.i=’0F’x THEN unit=”3390” 000033 ELSE unit=””
000034 submitstatus=KOGVUXSJ(“DEFRAG”, volser.i, unit, 500) 000035 END
000036 END 000037
Defragmenting DASD
Usage notes
n
The VUQUERY function call compiles a query request. This request uses the DF.DASD
VU template. The VOLSER and DEV_MODEL columns are the only columns required for
the query. Only data for DASD volumes with a fragmentation index greater that 800 is
retrieved. VUQUERY initializes a request handle which is passed to all subsequent VU
calls. The handle uniquely identifies this query request and is stored in variable
reqhdl
.
n
The requested data is fetched from CMS. The resulting data is a list of all the volsers that
have fragmentation indexes greater than 800, if there are any. The request is then
terminated and resources are freed (VUCLOSE) and, since the handle is no longer
needed, it is destroyed (VUDROP).
n
For each VOLSER satisfying the query criteria, a call to KOGVUXSJ is made to submit a
DASD defragmentation job for each volume. The KOGVUXSJ REXX program (found in
TKANSAM) takes a jobtype argument to determine the JCL to be submitted. The
VOLSER and target fragmentation index values are passed to KOGVUXSJ so that these
values may be substituted into control cards to defragment the specified DASD volume.
Migrating or Releasing Space on Non-SMS DASD
Introduction
This REXX exec accepts 3 arguments to determine if space on non-SMS-managed DASD
volumes should be reclaimed. A call to VUQUERY is issued to find all DASD volumes that are
n
online (MVS_STATUS<>0X02)
n
non-SMS-managed (SMS_CONVFG=0)
n
have a free space percentage that exceeds the value passed in the FREEPCT parameter
All volumes retrieved by the query are analyzed by calling REXX internal functions
estrelse
and
estmigrt
. These functions issue queries to predict the effects of DFDSS free space
release and of HSM dataset migration. Automation actions to initiate a DFHSM dataset
migration or submit a batch job to release free space from datasets on the volume are taken
depending on the values returned by these functions.
Example KOGVUX02
The line numbers in the following scenario are for reference purposes only.
000001 /* REXX */ 000002 IF ARG()=1 THEN
000003 PARSE VAR ARG(1) freepct days relspct . 000004 ELSE
000005 ARG freepct, days, relspct . 000006
000007 /* freepct Threshold percent of free space for Migrate/Release */ 000008 /* days Number of days of non-reference before dataset is */ 000009 /* considered for migration. */ 000010 /* relspct Percent of free space to be released from dataset */ 000011
000012 status=VUQUERY(“OMIISMS”, “reqhdl”, “DF.DASD”,, 000013 “VOLSER, DEV_TYPE, NUM_CYLS, TRK_P_CYL”,,
000014 “MVS_STATUS<>0X02 AND SMS_CONVFG=0X00 AND FREE_PCT<=”freepct*10) 000015
000016 IF status<>0 THEN SAY “VUQUERY error. status =” status 000017 ELSE DO
000018 /* VUQUERY was successful. Run Query */ 000019 status=VUOPEN(reqhdl)
000020 IF status<>0 THEN SAY “VUOPEN error. status =”status 000021 ELSE DO
000022 /* VUOPEN was successful, Fetch Data */ 000023 volser.0=0
000024 status=VUFETCH(reqhdl, “*”,,
000025 “volser., dev_type., numcyl., trkpcyl.”) 000026 IF status<>0 THEN SAY “VUFETCH error. status =”status 000027 /* Close request */
000028 closestatus=VUCLOSE(reqhdl)
Migrating or Releasing Space on Non-SMS DASD
000030 END
000031 dropstatus=VUDROP(reqhdl)
000032 IF dropstatus<>0 THEN SAY “VUDROP error. status =” dropstatus 000033 END
000034
000035 IF status=0 & volser.0>0 THEN DO
000036 SAY volser.0 “NON-SMS volumes found with <“ freepct”% free space” 000037 DO i=1 to volser.0 WHILE status=0
000038 /* Determine the type of DASD */ 000039 IF dev_type.i = ‘0E’x THEN unit=”3380” 000040 ELSE unit=”3390”
000041 /* Compute target free space=20% of volume capacity in tracks */ 000042 targetfreetrks=TRUNC(numcyl.i * trkpcyl.i * freepct/100 + .9) 000043 SAY “Attempting to reclaim” targetfreetrks” tracks on “volser.i 000044 /* See if DFDSS free space release from datasets will */ 000045 /* reclaim enough free space to satisfy the target. */ 000046 releasetrks=estrelse(volser.i,relspct)
000047 SAY “Estimated freespace reclaimed on” volser.i “is” releasetrks “tracks” 000048 IF releasetrks > targetfreetrks THEN DO
000049 /* Submit job to release free space up to the “relspct” */ 000050 SAY “Submitting job to release” releasetrks “tracks on” volser.i 000051 status=KOGVUXSJ(“RELSPACE”, volser.i, unit, relspct)
000052 IF status<>0 THEN
000053 SAY “RELSPACE job submittal error. status =” status 000054 END
Usage notes
n
This exec queries all volumes with a low amount of free space and, if found, passes the
names of the volumes to one or both of the subroutines estrelse and estmigrt for further
query and analysis.
n
Subroutines may be called repeatedly by the parent exec. Request handles are reused
inside the match.
n
The VUDROP function must be called by the parent routine to ensure that each request
handle is destroyed before completion.
000055 ELSE DO
000056 /* See if HSM Migrating datasets will reclaim enough */ 000057 /* free space to meet the target. */ 000058 migratetrks=estmigrt(volser.i,days)
000059 SAY “Estimated reclaimed space on” volser.i “is” migratetrks “tracks” 000060 IF migratetrks > targetfreetrks THEN DO
000061 SAY “Migrating datasets to get” migratetrks “tracks on” volser.i 000062 ADDRESS AFHOST,
000063 “OPER ‘F DFHSM,MIGRATE”,
000064 “VOLUME(“volser.i” MIGRATE(“days”))’” 000065 status=rc
000066 IF status<>0 THEN SAY “MIGRATE error. status =” status 000067 END
000068 ELSE IF (releasetrks + migratetrks) > targetfreetrks THEN DO 000069 /* Issue both
