OMEGAMON II for SMS Data Iterface OMEGACENTER Gateway for MVS Versio 340 GC32-9230-00 September 2002 Cadle Corporatio 201 North Douglas Street El Segudo, Califoria 90245-9796
Registered trademarks ad service marks of Cadle Corporatio: AF/OPERATOR, AF/PERFORMER, AF/REMOTE, Availability Commad Ceter, Cadle, Cadle Commad Ceter, Cadle Direct logo, Cadle Electroic Customer Support, Cadle logo, Cadle Maagemet Server, Cadle Maagemet Workstatio, CadleNet Portal, Cadle Techologies, CL/CONFERENCE, CL/SUPERSESSION, CommadWatch, CadleNet Commad Ceter, CT, CT/Data Server, CT/DS, DELTAMON, eba, eba*servicemoitor, eba*servicenetwork, ebusiess Assurace, ebusiess Istitute, ETEWatch, ItelliWatch, ItelliWatch Piacle, MQSecure, MQView, OMEGACENTER, OMEGAMON, OMEGAMON/e, OMEGAMON II, OMEGAMON Moitorig Aget, OMEGAVIEW, OMEGAVIEW II, PQEdit, Solutios for Networked Applicatios, Solutios for Networked Busiesses, ad Trasplex. Trademarks ad service marks of Cadle Corporatio: Alert Adapter, Alert Adapter Plus, Alert Emitter, AMS, Amsys, AutoBridge, AUTOMATED FACILITIES, Availability Maagemet Systems, Cadle Alert, Cadle Busiess Parter Logo, Cadle Commad Ceter/SetielMaager, Cadle CommadPro, Cadle CIRCUIT, Cadle edelivery, CadleLight, CadleNet, CadleNet 2000, CadleNet ebp, CadleNet ebp Access, CadleNet ebp Admiistrator, CadleNet ebp Broker Access, CadleNet ebp Cofiguratio, CadleNet ebp Coector, CadleNet ebp File Trasfer, CadleNet ebp Host Coect, CadleNet ebp Object Access, CadleNet ebp Object Browser, CadleNet ebp Secure Access, CadleNet ebp Service Directory, CadleNet ebp Uiversal Coector, CadleNet ebp Workflow Access, CadleNet ebusiess Assurace, CadleNet ebusiess Exchage, CadleNet ebusiess Platform, CadleNet ebusiess Platform Admiistrator, CadleNet ebusiess Platform Coector, CadleNet ebusiess Platform Coectors, CadleNet ebusiess Platform Powered by Roma Techology, CadleNet ebusiess Platform Service Directory, CCC, CCP, CEBA, CECS, CICAT, CL/ENGINE, CL/GATEWAY, CL/TECHNOLOGY, CMS, CMW, Commad & Cotrol, Coect-Notes, Coect-Two, CSA ANALYZER, CT/ALS, CT/Applicatio Logic Services, CT/DCS, CT/Distributed Computig Services, CT/Egie, CT/Implemetatio Services, CT/IX, CT/Workbech, CT/Workstatio Server, CT/WS,!DB Logo,!DB/DASD,!DB/EXPLAIN,!DB/MIGRATOR,!DB/QUICKCHANGE,!DB/QUICKCOMPARE,!DB/SMU,!DB/Tools,!DB/WORKBENCH, Desig Network, DEXAN, e2e, ebaa, ebaauditor, eban, ebanetwork, ebaapractice, ebp, ebusiess Assurace Network, ebusiess at the speed of light, ebusiess at the speed of light logo, ebusiess Exchage, ebusiess Istitute, ebx, Ed-to-Ed, ENTERPRISE, Eterprise Cadle Commad Ceter, Eterprise Cadle Maagemet Workstatio, Eterprise Reporter Plus, EPILOG, ER+, ERPNet, ESRA, ETEWatch Customizer, HostBridge, IterFlow, Cadle IterFlow, Lava Cosole, MessageMate, Messagig Mastered, Milleium Maagemet Blueprit, MMNA, MQADMIN, MQEdit, MQEXPERT, MQMON, NBX, NetGlue, NetGlue Extra, NetMirror, NetScheduler, OMA, OMC Gateway, OMC Status Maager, OMEGACENTER Bridge, OMEGACENTER Gateway, OMEGACENTER Status Maager, OMEGAMON Maagemet Ceter, OSM, PC COMPANION, Performace Pac, PowerQ, PQCofiguratio, PQScope, Respose Time Network, Roma, Roma Applicatio Maager, Roma Broker, Roma BSP, Roma Coector, Roma Developer, Roma FS/A, Roma FS/Access, RomaNet, Roma Network, Roma Object Access, Roma Secure, Roma WF/Access, Roma Workflow Access, RTA, RTN, SetielMaager, Somerset, Somerset Systems, Status Moitor, The Milleium Alliace, The Milleium Alliace logo, The Milleium Maagemet Network Alliace, TMA2000, Tracer, Uified Directory Services, Volcao ad ZCopy. Trademarks ad registered trademarks of other compaies: AIX, DB2, MQSeries ad WebSphere are registered trademarks of Iteratioal Busiess Machies Corporatio. SAP is a registered trademark ad R/3 is a trademark of SAP AG. UNIX is a registered trademark i the U.S. ad other coutries, licesed exclusively through X/Ope Compay Ltd. HP-UX is a trademark of Hewlett-Packard Compay. SuOS is a trademark of Su Microsystems, Ic. All other compay ad product ames used herei are trademarks or registered trademarks of their respective compaies. Copyright August 2002, Cadle Corporatio, a Califoria corporatio. All rights reserved. Iteratioal rights secured. Threaded Eviromet for AS/400, Patet No. 5,504,898; Data Server with Data Probes Employig Predicate Tests i Rule Statemets (Evet Drive Samplig), Patet No. 5,615,359; MVS/ESA Message Trasport System Usig the XCF Couplig Facility, Patet No. 5,754,856; Itelliget Remote Aget for Computer Performace Moitorig, Patet No. 5,781,703; Data Server with Evet Drive Samplig, Patet No. 5,809,238; Threaded Eviromet for Computer Systems Without Native Threadig Support, Patet No. 5,835,763; Object Procedure Messagig Facility, Patet No. 5,848,234; Ed-to-Ed Respose Time Measuremet for Computer Programs, Patet No. 5,991,705; Commuicatios o a Network, Patet Pedig; Improved Message Queuig Based Network Computig Architecture, Patet Pedig; User Iterface for System Maagemet Applicatios, Patet Pedig. NOTICE: This documetatio is provided with RESTRICTED RIGHTS. Use, duplicatio, or disclosure by the Govermet is subject to restrictios set forth i the applicable licese agreemet ad/or the applicable govermet rights clause. This documetatio cotais cofidetial, proprietary iformatio of Cadle Corporatio that is licesed for your iteral use oly. Ay uauthorized use, duplicatio, or disclosure is ulawful. 2 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
Cotets Preface..............................................................7 Sytax Diagrams.......................................................9 Documetatio Covetios.............................................11 Adobe Portable Documet Format........................................13 What s New i OG/MVS Versio 340...............................................15 Chapter 1. Before You Begi...............................................19 What this OG/MVS Fuctio Ca Do For You................................20 The VU API..........................................................21 VU API Eviromet...................................................23 IBM Storage Maagemet Subsystem......................................24 OMEGAMON II for SMS Data............................................25 Cadle Maagemet Server.............................................26 Chapter 2. VU API Compoets............................................27 Loggig O ad Off...................................................28 LOGON............................................................29 LOGOFF............................................................31 VU Fuctios.........................................................32 VU Templates........................................................34 OMEGAMON II for SMS Base Tables......................................39 Chapter 3. Puttig It All Together............................................43 Usig the VU API.....................................................44 Data Format Cosideratios.............................................45 LOGON to CMS......................................................46 Defragmetig DASD..................................................47 Migratig or Releasig Space o No-SMS DASD.............................50 Eablig Cachig o a List of 3390 DASD Volumes...........................55 Eablig Cachig o Productio 3390 DASD Volumes.........................57 LOGOFF from Cadle Maagemet Server ad Cleaup.......................59 Chapter 4. Istallatio ad Customizatio.....................................61 Requiremets for OMEGAMON II for SMS..................................62 Security.............................................................63 Addig the OG/MVS Loadlib to the CMS TKANMOD Cocateatio..............64 Addig the VUSERVER pluapplid.........................................65 Maual Procedures Required after Istallig OMEGAMON II for SMS V500 or V520..67 Icreasig OMEGAVIEW Virtual Termials..................................68 Cotets 3
Chapter 5. VU Fuctios..................................................69 VUQUERY..........................................................70 VUINSERT..........................................................73 VUDELETE..........................................................75 VUSUBST...........................................................78 VUOPEN...........................................................80 VUFETCH...........................................................82 VUCLOSE...........................................................85 VUDROP...........................................................86 Reuse of Request Hadles (REQHDLs).....................................87 Redirectig the Output of VUFETCH.......................................88 Fuctio Retur Codes.................................................89 Chapter 6. Sytax for Costructig a Search...................................95 Compariso Cosideratios.............................................96 Data Costats.......................................................97 Operators...........................................................98 Substitutio Symbols...................................................99 Expressios.........................................................100 Predicates..........................................................101 Predicate Evaluatio..................................................102 Search Coditios....................................................104 Appedix A. VU Templates.................................................105 Appedix 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 4 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
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 Appedix C. Idetifyig ad Locatig Messages................................. 199 Appedix D. Guide to Cadle Customer Support................................ 201 Base Maiteace Pla................................................202 Ehaced Support Services............................................206 Customer Support Cotact Iformatio....................................207 Glossary............................................................209 Idex............................................................215 Cotets 5
6 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
P Preface About this documet This documet describes the OMEGAMON II for SMS Data Iterface fuctio of OG/MVS. It cotais all the iformatio you eed to istall the fuctio at your site ad start usig OMEGAMON II for SMS data. This documet cotais: a descriptio of the fuctio s compoets a explaatio of the VU Applicatio Programmig Iterface a descriptio of the OMEGAMON II for SMS Cadle Maagemet Server scearios demostratig how to use the iterface The followig mauals comprise the OG/MVS documetatio set: OG/MVS Cofiguratio ad Customizatio Guide OG/MVS User s Guide OG/MVS Commad Referece Maual OG/MVS OMEGAMON II for SMS Data Iterface OG/MVS: Usig the Subsystem Loggig Facility Cadle Product Messages Maual For additioal iformatio o OMEGAMON II for SMS, cosult the OMEGAMON II for SMS User s Guide. Note: To make use of the OG/MVS OMEGAMON II for SMS Data Iterface, your OMEGAMON II for SMS product must be at a level curretly supported by Cadle Corporatio. Preface 7
Where to look for more iformatio For more iformatio related to this product ad other related products, please see the techical documetatio CD-ROM that came with your product techical documetatio iformatio available o the Cadle Web site at www.cadle.com olie help provided with this ad the other related products. Orderig additioal documetatio To order additioal product mauals, cotact your Cadle Customer Support represetative. We would like to hear from you Cadle welcomes your commets ad suggestios for chages or additios to the documetatio set. A user commet form, located at the back of each maual, provides simple istructios for commuicatig with the Cadle Iformatio Developmet departmet. You ca also sed email to UserDoc@cadle.com. Please iclude "OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340" i the subject lie. 8 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
Sytax Diagrams Sytax Diagrams This maual uses the format below to describe the sytax of the OG/MVS commads. Some commads ca be abbreviated. If a abbreviatio is applicable, it is show i paretheses ext to the commad ame. Read the sytax diagrams from left to right, from top to bottom, followig the path of the lie. The symbol below idicates the statemet is cotiued: > The symbol below idicates that a lie is cotiued from the previous lie: > The symbol below idicates the ed of a statemet: >< Required items appear o the horizotal lie (the mai path). STATEMENT Required Item >< Optioal items appear below the mai path. STATEMENT OPTIONAL ITEM >< Whe you ca choose from two or more items, they are stacked vertically. If you must choose oe of the items, the item at the top of the stack appears o the mai path. STATEMENT Required Choice1 >< Required Choice2 If choosig oe of the items is optioal, the etire stack appears below the mai path. STATEMENT Optioal Choice1 Optioal Choice2 >< Preface 9
Sytax Diagrams A arrow returig to the left above the mai lie idicates a item that ca be repeated. < STATEMENT Repeatable item >< A repeat arrow above a stack idicates that you ca make more tha oe choice from the stacked items, or repeat a sigle choice. If puctuatio marks, paretheses, arithmetic operators, or other symbols are show, they must be etered as part of the sytax. A operad ame edig i /s specifies a choice of oe or more of the operads, the various choices separated by space(s). For example: optio/s specifies optio1 optio2... A operad ame edig i,s specifies a choice of oe or more of the operads, the various choices separated by commas. For example: patter,s specifies patter1,patter2,... Default operads are uderlied. 10 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
Documetatio Covetios Documetatio Covetios Itroductio Cadle documetatio adheres to accepted typographical covetios for commad sytax. Covetios specific to Cadle documetatio are discussed i the followig sectios. Paels ad figures The paels ad figures i this documet are represetatios. Actual product paels may differ. Required blaks The slashed-b (b) character i examples represets a required blak. The followig example illustrates the locatio of two required blaks. beba*servicemoitorb0990221161551000 Revisio bars Revisio bars ( ) may appear i the left margi to idetify ew or updated material. Variables ad literals I examples of commad sytax, uppercase letters are actual values (literals) that the user should type; lowercase letters are used for variables that represet data supplied by the user. Default values are uderscored. LOGON APPLID (cccccccc) I the above example, you type LOGON APPLID followed by a applicatio idetifier (represeted by cccccccc) withi paretheses. Note: I ordiary text, variable ames appear i italics. Preface 11
Documetatio Covetios Symbols The followig symbols may appear i commad sytax: Table 1. Symbols i Commad Sytax Symbol Usage The or symbol is used to deote a choice. Either the argumet o the left or the argumet o the right may be used. Example: YES NO I this example, YES or NO may be specified. [ ] Deotes optioal argumets. Those argumets ot eclosed i square brackets are required. Example: APPLDEST DEST [ALTDEST] I this example, DEST is a required argumet ad ALTDEST is optioal. { } Some documets use braces to deote required argumets, or to group argumets 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 uderscored. Example: COPY ifile outfile - [COMPRESS={YES NO}] I this example, the COMPRESS keyword is optioal. If specified, the oly valid values are YES or NO. If omitted, the default is YES. 12 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
Adobe Portable Documet Format Adobe Portable Documet Format Pritig this book Cadle supplies documetatio i the Adobe Portable Documet Format (PDF). The Adobe Acrobat Reader will prit PDF documets with the fots, formattig, ad graphics i the origial documet. To prit a Cadle documet, do the followig: 1. Specify the prit optios for your system. From the Acrobat Reader Meu bar, select File > Page Setup ad make your selectios. A settig of 300 dpi is highly recommeded as is duplex pritig if your priter supports this optio. 2. To start pritig, select File > Prit... o the Acrobat Reader Meu bar. 3. O the Prit pop-up, select oe of the Prit Rage optios for All Curret page Pages from: [ ] to: [ ] 4. (Optioal). Select the Shrik to Fit optio if you eed to fit oversize pages to the paper size curretly loaded o your priter. Pritig problems? The prit quality of your output is ultimately determied by your priter. Sometimes pritig problems ca occur. If you experiece pritig problems, potetial areas to check are: settigs for your priter ad priter driver. (The dpi settigs for both your driver ad priter should be the same. A settig of 300 dpi is recommeded.) the priter driver you are usig. (You may eed a differet priter driver or the Uiversal Priter driver from Adobe. This free priter driver is available at www.adobe.com.) the halftoe/graphics color adjustmet for pritig color o black ad white priters (check the priter properties uder Start > Settigs > Priter). For more iformatio, see the olie help for the Acrobat Reader. the amout of available memory i your priter. (Isufficiet memory ca cause a documet or graphics to fail to prit.) For additioal iformatio o pritig problems, refer to the documetatio for your priter or cotact your priter maufacturer. Cotactig Adobe If additioal iformatio is eeded about Adobe Acrobat Reader or pritig problems, see the Readme.pdf file that ships with Adobe Acrobat Reader or cotact Adobe at www.adobe.com. Preface 13
Adobe Portable Documet Format 14 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
W What s New i OG/MVS Versio 340 This sectio provides a descriptio of the ew features that have bee icorporated ito OG/MVS Versio 340. TCP/IP coectivity ehacemets TCP/IP commuicatios have bee simplified by permittig you to optioally remove the AF packet header whe commuicatig betwee OG/MVS ad systems or applicatios that are uable to comply with the Cadle AF packet header protocol. You accomplish this by meas of a ew optio o the LINK DEFINE ad COMM START commads. I additio, ew SEND ad RECEIVE datatypes have bee added to the COMSDRCV REXX fuctio. You must use the SEND ad RECEIVE datatypes whe you wat to trasfer data over a lik havig the AF packet header tured off. New keywords have bee added to COMM START ad COMM STOP commads. The CONNECT_EXEC keyword o the COMM START commad idetifies a amed exec that rus wheever a coectio to the server is established ad is madatory whe you have specified AFPACKET(OFF). The CID keyword o the COMM STOP commad idetifies a particular coectio to a server to be stopped. A ew COMADMIN REXX fuctio provides GIVE ad TAKE optios that permit passig owership of a coectio from oe match to aother. Passig larger amouts of data o a TCP/IP match You ca ow pass more data to a idividual match. OG/MVS will permit passig a larger amout of parameter data to a REXX procedure. I additio, it will provide the capability to create a coversatio betwee matches so that multiple 32K packets ca be trasferred. This is accomplished by permittig the DATARPLY datatype to code the replylegth keyword o the COMSDRCV REXX fuctio. Automated peer-to-peer lik maagemet By predefiig lik attributes, it is ow possible to automatically establish coectios at OG/MVS startup. The followig product chages support this fuctio: The optioal RECOVERY keyword o the LINK DEFINE commad idicates that a INACTIVE lik havig a desired state of ACTIVE is to be automatically started whe the specified server becomes available. What s New i OG/MVS Versio 340 15
The ew ACTIVATE keyword o the LINK DEFINE commad idicates that a LINK START is to be automatically attempted for a particular likid, assumig a successful lik defiitio. The ew SCOPE keyword o the LINK START commad specifies those liks that are to be selected for LINK START processig accordig to their activatio state. Two ew startup parameters, HOSTNAME ad LINKDEFS are added. HOSTNAME(xxxxxxxx) overrides the default ame of the trusted hostames member i RKANPAR. The LINKDEFS(xxxxxxxx) parameter overrides the default ame of the lik defiitios member i RKANPAR. Durig product startup, whe TIMEOUT() is specified o the LINKDEFS keyword, it specifies the amout of time to wait for the LINK START commad issued immediately after processig the LINKDEFS member to complete before startup is allowed to cotiue. Chages to the OPER commad whe RESP is specified The OPER commad issues a MVS or subsystem commad. O this commad, the RESP parameter specifies that a set of lie variables will receive the respose text resultig from the commad. Additioal parameters have bee added to the OPER commad whe specified with the RESP parameter: TIMEOUT(pp,ss): The ew ss value specifies the umber of secods (from 1 through 3600) that OG/MVS is to wait for each respose message lie from a multi-lie write to operator before assumig the respose is complete. MAXLINES(): This ew parameter specifies that a respose is to be deemed complete whe the specified umber of lies is received. ENDMSG(prefix): This ew parameter specifies that the respose is to be deemed complete whe the specified prefix is ecoutered i oe of the respose lies. The ss value is also added to the OPERRESP OG/MVS startup parameter. I additio, the CMDSDRCV fuctio has bee modified such that whe it causes a OPER commad with RESP specified to be executed o a remote system, it also causes a AOCASE variable to be built whe the reply from the remote system is received. Additioal modificatios New global variables have bee added for COM matches. A DUB_AS_PROCESS commad, havig the same fuctio as the OG/MVS startup parameter of the same ame, has bee provided. Storage Costrait Relief The amout of storage costrait relief realized will vary depedig o OG startup parameters ad will be equal to (MAXMAT - MAXRUN) * 480 bytes. 16 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
Olie documetatio With Versio 340, Cadle Corporatio has moved AF/OPERATOR mauals from IBM BookMaster to Adobe FrameMaker. This move was made to better eable us to address our customers eeds by providig tools that ehace productivity. Oe of the results of the move is that it is o loger possible to create BookMaager versios of the AF/OPERATOR mauals. However, the mauals remai available olie i the Adobe PDF versio o CD-ROM ad are also available o the Cadle Corporatio website at www.cadle.com. The documetatio CD beig provided with this release has robust ad easy-to-use search capabilities. You ca search for iformatio i multiple volumes, multiple versios, ad across products. The CD also provides easy setup of search idexes with a sigle click of the mouse. If you wat to order prited copies of the documetatio, please cotact your Cadle Support Services represetative. Ehacemets to product documetatio Additioal documetatio about obtaiig SMF data has bee added to the OG/MVS User s Guide. Additioal documetatio about usig the Probe Directive, Probe Iput, ad Misc. Parms fields has bee added to the OMEGACENTER Status Maager User s Guide. What s New i OG/MVS Versio 340 17
18 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
1 Before You Begi Itroductio The OG/MVS OMEGAMON II for SMS Data Iterface fuctio adds the VU Applicatio Programmig Iterface (VU API), a bidirectioal iterface, to oe or more OMEGAMON II for SMS products. The VU API eables OG/MVS to query ad maipulate data collected by OMEGAMON II for SMS, to pass this statistical iformatio o to other applicatios, ad to execute actios o a storage system. This fuctio is iteded to support your implemetatio of system maaged storage for maagig ad cotrollig your eterprise s storage resources. Chapter Cotets What this OG/MVS Fuctio Ca Do For You................................. 20 The VU API........................................................... 21 VU API Eviromet.................................................... 23 IBM Storage Maagemet Subsystem........................................ 24 OMEGAMON II for SMS Data............................................. 25 Cadle Maagemet Server............................................... 26 Before You Begi 19
What this OG/MVS Fuctio Ca Do For You What this OG/MVS Fuctio Ca Do For You Itroductio The OMEGACENTER Gateway for MVS VU API eables you to automate DASD maagemet tasks. You ca, for example, have a automatio REXX exec to query the fragmetatio idex of DASD volumes ad submit batch jobs to defragmet those with a high fragmetatio idex moitor o-sms-maaged DASD volumes, to determie whe free space ca be reclaimed, ad iitiate free space release or HSM dataset migratio search for productio 3390 DASD volumes with disabled cachig ad eable cachig o all volumes or o selected volumes Audiece This fuctio is iteded for system programmers, storage admiistrators, data ceter persoel, ad others who are resposible for implemetig automatio procedures for DASD admiistratio, recoverability, availability, ad performace maagemet. What you eed to kow You must be familiar with these Cadle products: The curret versio of OG/MVS The curret versio of OMEGAMON II for SMS You will also eed a workig kowledge of REXX programmig laguage. For iformatio o REXX, cosult the followig IBM mauals: TSO Extesios Versio 2 REXX Referece TSO/E REXX/MVS Referece 20 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
The VU API The VU API Itroductio to the VU API The VU Applicatio Programmig Iterface (VU API) is a sychroous commuicatios iterface. It establishes a VTAM coectio betwee OG/MVS ad OMEGAMON II for SMS, makig OG/MVS a cliet of the Cadle Maagemet Server (CMS ) facility. The VU API cosists of the followig compoets: Extesios to the LOGON ad LOGOFF commads REXX fuctio package VU Templates TKANSAM (samples) Commads This fuctio modifies two OG/MVS commads: AF LOGON AF LOGOFF These commads establish ad termiate LU0 sessios with CMS. REXX fuctio package The REXX fuctio package is a set of 8 REXX callable fuctios which provide a applicatio programmig iterface for automatio procedures ruig i the OG/MVS address space. Fuctio VUQUERY() VUINSERT() VUDELETE() VUSUBST() VUOPEN() VUFETCH() VUCLOSE() VUDROP() Descriptio Compiles a query request. Compiles a isert request. Compiles a delete request. Substitutes symbols ito compiled requests. Executes a request. Retrieves oe or more rows of a table. Closes a active request. Destroys a request. For a complete descriptio of each VU fuctio, see VU API Compoets o page 27. Before You Begi 21
The VU API VU Templates VU Templates are Cadle supplied views that geerate predefied requests used i query, isert, ad delete operatios. Each VU Template specifies a view of the CMS base tables. A view defies the tables, colums, ad rows that the cliet applicatio eeds. A VU Template ca retrieve all or a subset of the colums cotaied i oe or more CMS base tables. TKANSAM TKANSAM cotais sample REXX programs desiged to carry out specific storage maagemet tasks. TKANSAM programs are ot iteded for you to use i their preset state. Cadle has provided them as models you ca refer to while writig your ow REXX execs. If you wat to use oe of these programs, you will eed to customize it to suit your eviromet. The sample programs used i this maual match those i TKANSAM. 22 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
VU API Eviromet VU API Eviromet System Maaged Storage The VU API is iteded for your automated storage maagemet eviromet. You use Cadle s OMEGAMON II for SMS ad the IBM Storage Maagemet Subystem to moitor, cotrol, ad automate storage systems across your eterprise. You may have additioal Cadle Availability Maagemet Systems products istalled. Diagram of the VU API operatig eviromet This figure illustrates the relatioship betwee the VU API, OG/MVS, ad SMS i your eterprise. Compoets The basic operatig eviromet for the VU Applicatio Programmig Iterface cosists of these compoets: OG/MVS OMEGAMON II for SMS Cadle Maagemet Server Storage Maagemet Subsystem (SMS) Before You Begi 23
IBM Storage Maagemet Subsystem IBM Storage Maagemet Subsystem Itroductio The IBM Storage Maagemet Subsystem (SMS) automates storage maagemet. SMS gives the storage admiistrator the ability to cetralize, automate, ad prioritize storage allocatio by the performace characteristics of the storage media. SMS does ot provide realtime storage data. SMS compoets SMS cosists of hardware ad software compoets. The SMS hardware compoets are cache cotrol uits DASD Optical storage devices The SMS software compoets are: Compoet DFSMSdfp DFSMSdss DFSMShsm DFSMSrmm Descriptio A IBM data facility product that provides storage, data, program, ad device maagemet fuctios. A dataset services product that provides data movemet, copy, dump, ad space maagemet fuctios. A hierarchical storage maager that provides backup, recovery, migratio, ad space maagemet fuctios. A removable media maager that provides maagemet fuctios for removable media such as tape cartridges, reels, ad optical volumes. 24 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
OMEGAMON II for SMS Data OMEGAMON II for SMS Data Itroductio OMEGAMON II for SMS is Cadle s realtime performace moitor for your storage resources. It provides status idicators, data displays, ad built-i actio capabilities. OMEGAMON presets a high-level overview of the status of your storage resources through the Storage Maagemet Status Overview pael. OMEGAMON II for SMS cosists of the followig compoets: applicatio address space Cadle Maagemet Server (data collectio address space) Cadle Subsystem What data OMEGAMON collects OMEGAMON II for SMS uses data collectio programs, probes, that execute i the data collectio address space. Probes collect iformatio o: Chael Path Logical Cotrol Uit Cache Cotrol Uit SMS storage groups user-defied storage groups datasets applicatios Data Facility Hierarchical Storage Maager (DFHSM or HSM) OMEGAMON II for SMS maages DASD device statistics ad dataset I/O statistics with its Cadle Maagemet Server facility. Before You Begi 25
Cadle Maagemet Server Cadle Maagemet Server Itroductio The Cadle Maagemet Server (CMS) is a data collector that rus i its ow address space ad collects, maages, ad distributes data for OMEGAMON II for SMS. It stores the statistical iformatio the probes gather i rectagular data structures (tables, colums, ad rows). CMS allows multiple host queries from a sigle poit. You ca sed a query to every CMS o your system ad receive data back i oe homogeeous table. The VU API provides direct access to the data maaged by Cadle Maagemet Server. This gives you the ability to query, update, isert, ad delete data i CMS tables. The CMS facility cosists of the: CMS Catalog base tables Applicatio Programmig Iterface Cadle Maagemet Server Catalog The CMS Catalog is the fuctioal equivalet of the data dictioary for a database maagemet system. The Catalog cotais defiitios of CMS objects (base tables, colums, request hadles, views, ad applicatios) ad iformatio o their iterrelatioship. No data ca be queried or maipulated uless it is defied i the CMS catalog. Cadle Maagemet Server base tables Base tables are the rectagular data structures i which OMEGAMON II for SMS stores iformatio. A table is a logical structure of data elemet values arraged i rows of colum values. A table colum represets oe attribute of a data object (for example, I/Os per secod for a volser o a specific DASD volume). Every colum has a uique ame idetifyig its data type. A table row represets a occurece of the data (for example, 0.8 for I/Os per secod). Rows do ot have ames. The umber of rows idicates how may times the table data occurs. I a realtime server, the umber of rows a table cotais is upredictable; they may vary widely over a few millisecods. A set of predefied OMEGAMON II for SMS probes build each CMS table. The structure of the base tables is fixed (See OMEGAMON II for SMS Base Tables o page 137). To uderstad the data retured from a query to CMS, you must kow the desig of the idividual base tables. 26 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
2 VU API Compoets Itroductio Cotets This chapter describes the compoets eeded for a successful data query ad maipulatio. I Puttig It All Together o page 43, the scearios will demostrate how you ca use these compoets to 1. log o to CMS 2. use the VU fuctios withi the framework of various VU templates to acquire data from base tables 3. log off Loggig O ad Off..................................................... 28 LOGON.............................................................. 29 LOGOFF............................................................. 31 VU Fuctios.......................................................... 32 VU Templates.......................................................... 34 OMEGAMON II for SMS Base Tables........................................ 39 VU API Compoets 27
Loggig O ad Off Loggig O ad Off Itroductio The VU API is implemeted through extesios to the LOGON ad LOGOFF AFHOST eviromet commads ad by a REXX fuctio package. This sectio describes the LOGON ad LOGOFF commads. Other compoets of the REXX fuctio package are discussed i VU Fuctios o page 32. Modificatios The LOGON ad LOGOFF commads have bee modified to establish ad termiate LU0 sessios to a VU server dialog defied i the CMS address space where OMEGAMON II for SMS probes are istalled. The VU server dialog dispatches a process after a successful LOGON. Refer to Sytax Diagrams o page 9 for covetios used i describig commad sytax. 28 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
LOGON LOGON Itroductio Sytax LOGON iitiates a LU0 sessio with the VU server dialog that resides i the CMS address space used by OMEGAMON II for SMS for data collectio. LOGON appltype APPLID(applid) NAME(applame) >< optio(s) Optios: DATA(text) INTERVAL(time) LTERM(luid) PASSWORD(password) SSIZE() TRACE USERID(userid/password) The followig parameters have modified meaigs for this ehacemet. Igore all other optios whe establishig a VU API sessio. appltype APPLID(applid) The type of VTAM applicatio. Eter CTDS to establish a VU API sessio. The APPLID of the VTAM applicatio. Whe you defie CMS as the appltype, applid specifies the VTAM LU0 APPLID of the VU server dialog that rus the CMS address space used by OMEGAMON II for SMS for data collectio. Note: This applid must be idetical to the pluapplid specified with the START commad i member KDSCNFG. See Addig the VUSERVER pluapplid o page 65. NAME(applame) TRACE USERID(userid/password) A user-defied ame assiged to the LU0 sessio. Whe specified durig a successful logo, it is passed as a argumet to subsequet VU API fuctio calls. If specified, eables diagostic messages. The user ID ad password required to validate access to CMS. The password appears as asterisks i the system log. A CMS sessio requires a user ID ad password combiatio that is kow to the security system istalled i the CMS address space. See Security o page 63 for more iformatio. VU API Compoets 29
LOGON Retur Codes Retur Code 0 VTAM sessio successfully established. 16 Ivalid sytax. No-zero Logo failed. Reaso Commets Examples The LOGON commad is ofte issued by a startup REXX exec. The maximum logo time default is 20 secods, uless overridde by the LOGONTLM startup optio. The rage available is 1 to 99 secods. See the AF/OPERATOR Cofiguratio ad Customizatio Guide for more iformatio. You must establish a sessio betwee the CMS address space ad OMEGAMON II for SMS s address space (data collectio) before you make a data query or request. Followig is a example of the LOGON commad i a REXX exec used to log oto a CMS sessio through the VTAM APPL RGOGVU00. OG/MVS supplies the CT/Egie exteral security system with the user ID CANUSER ad the user password CANPSWD. The coectio ame, OMIISMS, is used to idetify the commuicatios sessio. 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 ca establish multiple sessios to multiple address spaces or to the same CMS address space. All examples show i Puttig It All Together o page 43 reuse the same coectio created by this example. 30 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
LOGOFF LOGOFF Itroductio Sytax LOGOFF termiates a LU0 sessio with the VU server dialog that resides i the CMS address space used by OMEGAMON II for SMS for data collectio. LOGOFF ame ame The ame (applame) assiged to the LU0 sessio by the NAME operad i the LOGON commad that iitiated the sessio.this operad is required. Ay active requests are closed ad dropped before logoff processig completes. Retur Codes Retur Code Reaso 0 VTAM sessio successfully termiated. 16 Ivalid sytax. No-zero Logoff failed. Examples Termiate a sessio with the data collectio address space by issuig the LOGOFF commad. This is a example of the LOGOFF commad i a REXX exec used to log off of a CMS sessio through the VTAM APPL OMIISMS: ADDRESS AFHOST LOGOFF OMIISMS status=rc IF status<>0 THEN DO SAY LOGOFF FROM APPLID(RGOGVU00) FAILED END Ay outstadig queries or data maipulatio requests are closed ad dropped automatically with a error followig successful logoff processig. Actio requests submitted to OMIISMS cotiue to execute. VU API Compoets 31
VU Fuctios VU Fuctios Itroductio The REXX fuctio package is a set of REXX callable fuctios that provides a applicatio programmig iterface for automatio procedures ruig i the OG/MVS address space. The API is supported oly for REXX execs that execute withi the OG/MVS address space. Process The VU fuctio process is as follows: 1. LOGON establishes a sessio to the CMS address space. 2. The ame of the sessio is the passed to the VUQUERY, VUINSERT, or VUDELETE fuctio i order to compile a query, isert, or delete request. Compilatio of requests allows reuse of requests without recompilig ad miimizes the resources required to iterpret the request. 3. Compiled requests ca be of more geeral use by itroducig substitutio symbols that allow values to be assiged after compilatio. You must substitute values before you use VUOPEN to execute a request by a call to the VUSUBST fuctio. 4. CMS allows the query ad maipulatio of data similar to that of a relatioal database maagemet system. Compiled requests are executed by callig the VUOPEN fuctio. Whe you execute VUOPEN, the data collected for a query is assembled ito a result table. 5. After a successful query, you ca fetch the rows i the result table by callig the VUFETCH fuctio. 6. Whe request processig is completed, ad all rows have bee fetched for queries, you ca call the VUCLOSE fuctio to release resources occupied by the result table, if ay. 7. Additioal calls to VUSUBST ad VUOPEN ca be issued after VUCLOSE is issued to re-execute a request without recompilig. 8. A call to the VUDROP fuctio releases resources occupied by a compiled request. Oce VUDROP is executed, the dropped request is o loger valid for ay subsequet VU API fuctio calls. 9. LOGOFF termiates the sessio with the CMS address space. All compiled requests, result tables, ad associated resources are automatically released durig the logoff. 32 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
VU Fuctios Fuctio sequece The followig table shows the ormal processig sequece of VU API service calls. API Commad or Prerequisite Descriptio Fuctio LOGON commad Active SLU APPLID Establish LU0 sessio to CMS. VUQUERY(), VUINSERT(), or VUDELETE() fuctios VUSUBST() fuctio VUOPEN() fuctio LOGON VUQUERY(), VUINSERT(), or VUDELETE() fuctio VUQUERY(), VUINSERT(), or VUDELETE() fuctio Compile ad create CMS request. Substitute values ito compiled statemet before executio. Execute a request. VUFETCH() fuctio VUOPEN() Retrieve oe or more rows of result table. VUCLOSE() fuctio VUOPEN() Close a active request. VUDROP() fuctio VUQUERY(), VUINSERT(), or VUDELETE() fuctio Destroy a compiled request. If the request to be dropped is ot yet closed, a VUCLOSE will be issued before the request is dropped to esure itegrity of isert, delete, or update requests. LOGOFF commad LOGON Termiate LU0 sessio with CMS. Ay outstadig requests are automatically closed ad dropped as a result of the sessio termiatio. Complete descriptios of each fuctio are provided i VU Fuctios o page 69. VU API Compoets 33
VU Templates VU Templates Itroductio VU Templates geerate predefied queries ad data maagemet requests used by the VUQUERY, VUINSERT, ad VUDELETE fuctios. Each VU Template defies the followig: base table ame or ames colum ames of the base table(s) search criteria VU Template amig covetio VU Template ames begi with the letters DF, the Cadle product idetifier for OMEGAMON II for SMS. Modifyig views A view associates a table with a list of colums ad a filter (which idetifies specific rows of the table). You caot add to the tables or colums defied i a view, but you ca arrow a view s focus to fetch oly the data required by a applicatio. You ca modify a view defiitio to select a subset of the colum data rearrage the order of the colums fetched retrieve oly a subset of rows by addig to the search criteria To modify the colums ad rows selected by a view, use the list of colum ames ad search criteria argumets. The list of colum ames specifies the colums to be retrieved. The search criteria optioal argumet specifies the rows to be retrieved. Usig a list of colum ames Use the VUQUERY list of colum ames argumet to specify the list of colums. The argumet is a character strig specifyig a subset of the desired colums. The colum ames must be separated by commas ad must be a subset of the colum ames idetified by the VU Template. You ca rearrage the order of colums fetched by a query or exclude uecessary colums to improve data collectio performace. See VUQUERY o page 70 for additioal iformatio. 34 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
VU Templates Usig search criteria Use the VUQUERY ad VUDELETE optioal search criteria argumet to determie the rows fetched or deleted. The criteria you specify is logically ANDed to the search criteria specified by the VU Template. This optio eables you to make more selective query ad delete operatios. Search criteria may cotai substitutio symbols that allow a VU Template to be reused without beig recompiled. Substitutio symbols appear as? i the search criteria argumets. See VUQUERY o page 70 ad VUDELETE o page 75 for additioal iformatio. Joied tables VU Templates that refer to more tha oe base table are created by joiig the tables by oe or more commo colum values. You ca oly query VU Templates of joied tables; you caot isert or delete rows. All VU Templates for joied tables are applicable oly to VUQUERY fuctio calls. Template descriptios The followig table lists the ames of the VU Templates icluded i the VU API, the page i VU Templates o page 105 where a detailed descriptio of each template ca be foud, the fuctio it performs, ad a descriptio of iformatio that the view cotais. VU Template Name Page Valid VU Template Descriptio Operatios DF.ACTION page 107 VUQUERY List of all the DASD volume ad dataset actios available from OMIISMS. DF.ACTIONREQ page 107 VUQUERY, VUINSERT, VUDELETE Access ad maipulate actio requests issued by OMIISMS. Queries retur actio request status. Iserts submit ew actio requests. Deletes cacel pedig requests or remove completed actio requests. DF.ACTIONRESP page 109 VUQUERY Resposes issued by completed actio requests. DF.ACTIVEJOB page 109 VUQUERY Curret active jobs i the system. DF.CACHECU page 110 VUQUERY Cache cotrol uit status ad performace. DF.CACHEDETAIL page 111 VUQUERY Detailed cached DASD device performace statistics. DF.CACHEDEVICE page 112 VUQUERY Cached DASD device performace statistics. DF.CACHEENV page 112 VUQUERY Cache collectio iterval iformatio. DF.CHANNELPATH page 113 VUQUERY Chael path iformatio by CHPID. VU API Compoets 35
VU Templates VU Template Name Page Valid Operatios VU Template Descriptio DF.DASD page 113 VUQUERY Direct Access Storage Devices. DF.DASDCACHE page 114 VUQUERY List DASD volume ad cache performace data for all olie DASD volumes. DF.DASDCACHEBYJOBNAME page 115 VUQUERY List DASD volume ad cache performace data for all volumes beig accessed by a specific address space. DF.DASDCACHEDETAIL page 116 VUQUERY List DASD volume ad detailed cached performace data for all olie DASD volumes. DF.DASDUSER page 117 VUQUERY List of address spaces ad datasets beig accessed o a specific DASD volume. DF.DSBYASID page 117 VUQUERY List of all datasets beig accessed by a specific address space, give its address space ID. DF.DSBYDSNAME page 118 VUQUERY DSCB ad space iformatio for each occurrece of a specific cataloged dataset o 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 ad space iformatio for all datasets o a volume. DF.DSENQ page 119 VUQUERY List of jobames ad ENQs for a specified dataset ame. DF.DSIOBYDSNAME page 120 VUQUERY Data set I/O ad cache performace statistics by dataset ame. DF.DSIOBYJOBNAME page 121 VUQUERY Dataset I/O ad cache performace statistics by job ame. DF.DSIOBYVOLUME page 121 VUQUERY Dataset I/O ad cache performace statistics by volume. DF.DSLOC page 122 VUQUERY VOLSER ad device umber for a specified dataset ame. DF.DSSMS page 122 VUQUERY SMS iformatio for a specific dataset. DF.HSMCDS page 122 VUQUERY Space utilizatio iformatio for HSM cotrol datasets. DF.HSMDSRV page 123 VUQUERY HSM recovery versios for a specified dataset. Oe row for each backup versio is available for recovery. 36 OMEGACENTER Gateway for MVS OMEGAMON II for SMS Data Iterface Versio 340
VU Templates VU Template Name Page Valid Operatios DF.HSMFUNDA page 123 VUQUERY Processig statistics for major HSM fuctios withi the curret HSM processig iterval. DF.HSMFUNST page 124 VUQUERY Hold status ad activity status for major fuctios withi HSM. DF.HSMREQ page 124 VUQUERY, VUDELETE VU Template Descriptio Active ad queued HSM request processig iformatio. DF.HSMSTATUS page 125 VUQUERY Status ad activity iformatio for HSM collected withi the curret HSM processig iterval. DF.HSMSTORAGE page 125 VUQUERY Status of virtual storage i the HSM address space. DF.LCU page 126 VUQUERY Logical cotrol uit iformatio from RMF. DF.LCUIORATE page 126 VUQUERY Logical cotrol uit iformatio from RMF with total DASD I/O rate. DF.RMFENV page 127 VUQUERY Iformatio about the RMF eviromet (collectio iterval) for the curret MVS system. DF.SMSCONFIG page 128 VUQUERY SMS base cofiguratio data. DF.SMSDATACLASS page 128 VUQUERY SMS data class iformatio. DF.SMSDSBYDSNAME page 129 VUQUERY SMS maaged dataset attributes with SMS classes. DF.SMSDSBYVOLUME page 130 VUQUERY List of detailed iformatio for a SMS maaged dataset, give the DASD volume serial umber. DF.SMSDSIOBYJOBNAME page 131 VUQUERY Allows compariso 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 compariso of dataset I/O statistics with SMS storage class objectives for all datasets o a specific SMS maaged DASD volume. DF.SMSMANAGEMENTCLASS page 133 VUQUERY SMS maagemet class iformatio. DF.SMSSTORAGECLASS page 133 VUQUERY SMS storage class iformatio. DF.SMSSTORAGEGROUP page 134 VUQUERY SMS storage group iformatio. DF.SYSTEMENV page 134 VUQUERY MVS ad DFP eviromet iformatio. VU API Compoets 37