IBMr IBM IMS Best practices Managing resources in an IMSplex with OM, type-2 commands, and SPOC Sandy Stoob IMS Development Anu Vakkalagadda IMS Development Janna Mansker IMS Development David Hanson IMS Information Development Issued: December, 2013
Table of Contents Managing resources in an IMSplex with OM, type-2 commands, and SPOC...1 Executive Summary...3 Introduction...4 Common Service Layer (CSL)...5 Operations Manager (OM)...5 Single Point of Control (SPOC)...6 Types of SPOC...7 Best practice: Enable OM and SCI for type-2 commands...8 Best practice: Verify command return/reason codes in automated SPOC programs...9 Global Command Status...9 Best Practice: Enable global status in the IMSplex...10 Best Practice: Issue single commands to set multiple statuses with global command status...11 Serialized Program Management...11 Best Practice: Diagnose resource problems with QUERY commands...12 Best practice: Use QUERY commands to identify work-in-progress before using online change...13 Best practices...15 Conclusion...16 Further reading...17 Notices...18 Trademarks...19 Contacting IBM...19 Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 2 of 19
Executive Summary This article provides an overview and comparison of the various methods of managing IBM Information Management System (IMS) resources in an IMSplex with the administrative functions of IMS Operations Manager (OM). Managed resources include IMS database and program definitions, Fast Path routing codes, and transaction resources. Using OM type-2 commands maximizes IMS availability and ease of use while minimizing errors and downtime. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 3 of 19
Introduction Over time, IMS has introduced more dynamic tools to define and manage resources, including the Common Service Layer, Single Point of Control, and type-2 commands introduced in IMS version 8.1; and global database and transaction status and global serial programs introduced in IMS 10.1. This article offers some best practices for managing resources and their status in an IMSplex. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 4 of 19
Common Service Layer (CSL) An IMSplex is one or more IMS subsystems in a sysplex that can work together as a unit. The IMS Common Service Layer (CSL) is a collection of IMS system address spaces that provide the infrastructure needed for systems management tasks in the IMSplex. The CSL address spaces include Operations Manager (OM), Resource Manager (RM), Structured Call Interface (SCI), and Open Database Manager (ODBM). When IMS systems are joined together into sharing groups (sharing databases, resources, or message queues) in an IMSplex, systems management becomes more complex. The CSL address spaces and associated functions reduce the complexity of managing multiple IMSs in the IMSplex. The CSL provides a single-system perspective of the entire IMSplex. In particular, OM is very useful for defining and managing resources in an IMSplex. Operations Manager (OM) OM provides an API through which commands can be issued to the members of the IMSplex. When OM receives a command it parses and then routes the command to all of the command processing clients that have registered for the command. Command processing clients within an IMSplex can include any of the following: An OM address space that processes the QUERY IMSPLEX command. An IMS address space that processes type-1 and type-2 commands. An IMS Connect address space that processes type-2 commands. An ODBM address space that processes type-2 commands. An RM address space that processes type-2 commands. OM parses the input command issued on the OM API and provides the command processing client the parsed command blocks. The input command is parsed based on simplified Base Primitive Environment parsing rules. After a command processing client receives and processes a command, it sends a response back to OM. OM consolidates the command responses from each of the IMSplex members into a single response for presentation to the command originator. OM only supports commands entered through the OM API the CSLOMCMD or CSLOMI requests. Commands to OM cannot be entered through the system console, master terminal, end user terminal, DL/I application program CMD/ICMD calls, APPC client, or through the OTMA interface. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 5 of 19
IBM provides the TSO SPOC interface as a simple way to use OM commands without creating a customized application that issues CSLOMCMD or CSLOMI requests. You can use TSO SPOC to submit type-1 or type-2 commands to manage your IMSplex. You can also write Batch SPOC or REXX SPOC programs to manage the IMSplex, or issue commands through the IMS Enterprise Suite Connect APIs or write your own application program that uses the OM API. The Explorer for Administration component of the IBM Tools Base Administration Console for z/os that allows you to manage multiple IMSplexes from a web interface. You can define exit routines that are given control on OM input and output. You can use these exits to manage the parameters of input messages and handle command responses. If an OM input exit routine is defined, OM passes any incoming command to the exit before it is processed. The exit can then pre-process the command and either reject it or allow OM to process it normally. For example, when the OM input exit receives a command with NAME(*), the exit can reject the command. If an OM output exit routine is defined, OM passes the consolidated output, or any unsolicited command output that is received, to the exit routine. You can define the exit routine to only process the unsolicited output if desired. For example, when the OM output exit receives unsolicited command output, it can send a message to an alternate destination with the input command, the member name, type and subtype that sent the unsolicited output, and the command response or message segment that was received as unsolicited output. Single Point of Control (SPOC) A single point of control (SPOC) is a program that allows you to manage operations of one, many, or all of the IMS systems in an IMSplex simultaneously, instead of using the master terminal for each IMS system individually. A SPOC registers with SCI and OM and uses the OM API (CSLOMCMD or CSLOMI request) to communicate with OM. The OM API request is routed by SCI to a single OM. Through SCI, OM then communicates with the command processing clients (for example: IMS systems) that can process the command. OM returns the consolidated command response from all of the command processing clients. A SPOC is optional in an IMSplex. The existing command interfaces for the WTOR, MTO, and E-MCS console of ICMD/CMD DL/I calls are supported only for type-1 commands. If you want to use type-2 commands, you must use a SPOC. You can use a SPOC instead of the z/os master console, IMS master terminal, or user terminal for most command processing. A SPOC provides the following functions and benefits to an IMSplex: Single-system view of an IMSplex Consolidated display of command responses from multiple IMS systems Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 6 of 19
Ability to send messages to IMS terminals connected to any IMS control region in the IMSplex Allows users to define input user exit routines to view and modify or reject command parameters and set return and reason codes Allows users to define output user exits to view and modify command responses and unsolicited messages Types of SPOC TSO SPOC TSO SPOC is the IMS-provided, ISPF-based system management application for IMSplexes. You can start the TSO SPOC using the IMS Application Menu. TSO SPOC uses the CSLOMCMD OM API request to issue commands to members of the IMSplex and receive command responses. The command output can be saved to an output data set. TSO SPOC also provides other features that can help you manage an IMSplex: Displays the OM audit trail log which records command input, command responses, and selected system messages from across the IMSplex. Provides the Manage Resources interface to manage DRD resources (DRD UI) that allows users to create, query, update, and delete various IMS resources online. Supports PF keys to scroll up, scroll down, scroll right, scroll left, and retrieve the last command. Allows you to sort command responses by any of the output columns. For example, you could issue a QUERY MSNAME SHOW(SYSID) command and sort the local system ID (SIDL) column in ascending order to see all of the local SIDs for an IMS system. Batch SPOC The batch SPOC program is a utility that uses OM API services to submit IMS commands to an IMSplex and receive the command responses. The utility accepts any commands that are supported by the OM API. The batch SPOC utility is invoked by using standard JCL statements.the SYSIN file is provided by the user and contains the commands that the user wants to run. The commands are run serially. When one command completes, the next command is run until all of the records from the SYSIN file are processed. The SYSPRINT file contains the formatted command responses. If more than one command is issued, the responses will appear in the same order as the commands were entered in the SYSIN file. REXX SPOC API The REXX SPOC API allows a user-written REXX program to issue IMS commands and process the command responses. The command response is returned to the REXX SPOC Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 7 of 19
API in the form of XML statements. The command responses can be retrieved by the REXX program using the following requests: CSLULGTS This request retrieves the command response to a stem variable. Each row in the stem variable contains an XML statement. The user-supplied application must parse the command output using its own XML parser. The REXX program can be autonomic to process the command response and take action accordingly. For example, a QUERY TRAN command can be issued and if the status of the transaction is STOSCHD then the program can issue a UPD TRAN START(SCHD) command. CSLULGTP This request retrieves the command response from OM and puts the command response to a REXX stem variable. IMS CSLULGTP program parses the XML command response returned by OM and returns the response in the stem variable. The REXX program can be coded to process only certain suffixes in the stem variables. For example, stem.ctl.rc and stem.ctl.rsn are the stem variables that contain the command return code and command reason code. Vendor or user-written (RYO) SPOC A user written SPOC or a vendor SPOC is a program that issues the CSLOMCMD or CSLOMI OM API requests to issue commands to OM and process the command responses. Connect API for Java The Connect API for Java can be used to issue IMS commands that are supported through the Open Transaction Manager Access (OTMA) interface and IMS Connect, and process the command responses. Because type-2 commands are supported, you can implement a SPOC program in Java that communicates with your IMSplex over TCP/IP. IMS Explorer for Administration Introduced in IMS V13, the IMS Explorer for Administration is a web-based GUI for IMS systems management. You can query, start, and stop some IMS resources from an easyto-use browser interface. The IMS Explorer for Administration can discover IMS resources, and show the health of the resources and relationships between them. The console is integrated with and ships as an extension of the Administration Console component of IBM Tools Base for z/os 1.4. IMS Connect is required in addition to OM. Any number of SPOCs can be active at any time in an IMSplex. Best practice: Enable OM and SCI for type-2 commands Enable OM and SCI to take advantage of type-2 commands. IMS type-2 commands provide the following benefits: Filters and generic (wild card) parameter support for resource name selection Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 8 of 19
Filtering output fields for QUERY command output Elimination of resource name and command keyword conflicts Simplified set of command verbs Parallel command processing More informative completion codes, completion code text, and error text QUERY commands that show more information than IMS type-1 /DISPLAY commands QUERY command SHOW keyword filters to minimize unwanted response data More informative NOTINIT status for QUERY commands Best practice: Verify command return/reason codes in automated SPOC programs In REXX SPOC, batch SPOC, and Java-based SPOC programs it is important to verify the command return/reason code before the command output is processed and to take actions to handle the command errors. Failing to handle command errors in automated SPOC programs can result in bad commands being issued to members of the IMSplex. Global Command Status Global command status is an IMS function that can be used to manage global resource status in an IMSplex. You can use global command status to ensure that a resource has the same status on all IMS systems in an IMSplex. IMS uses the Resource Manager (RM) resource structure to maintain command status for databases, DEDB areas, and transactions across an IMSplex. Maintaining a global status for these resources enables all IMS systems to view databases, DEDB areas, and transactions in an IMSplex as single databases, areas, and transactions. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 9 of 19
Best Practice: Enable global status in the IMSplex Consider enabling global status in the IMSplex to ensure all IMS systems that share the resource have the same status for the resource. To use global command status specify the appropriate PLEXPARM value during IMS initialization in either the DFSDFxxx or DFSCGxxx IMS PROCLIB member data set or dynamically using the UPD IMS TYPE(PLEXPARM) command. The status of global resources is set by the command master IMS that processes the IMS commands that support global status. IMS systems obtain the global status for their resources after a restart. When global status is enabled, you can (for example) stop a database globally, and any IMS system that joins the IMSplex recognizes that the database is stopped. Similarly, an IMS system that joins the IMSplex can be prevented from accessing or updating a database that is in use by an offline process. After an online change is committed, global status is obtained for all databases, DEDB areas, or transactions being added. Global command status is also obtained from RM after a CREATE DB and CREATE TRAN command. Databases, DEDB areas, and transactions cannot be used until global status for the resources added is obtained and processed. If an error occurs obtaining or processing the global status for the added resources, the added resources are marked in error. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 10 of 19
Best Practice: Issue single commands to set multiple statuses with global command status Only the last significant global status is maintained in the RM structure for affected resources. If multiple update commands are issued for a resource, only the most recent command status is maintained and available to be queried as the global status. For example, if an UPD TRAN NAME(TRANA) STOP(SCHD) command is issued, the global status of STOSCHD is maintained for transaction TRANA. If an UPDATE TRAN NAME(TRANA) STOP(Q) command is then issued, the global status of STOQ is maintained for transaction TRANA. To maintain both the STOSCHD and STOQ status, an UPDATE TRAN NAME(TRANA) STOP(Q,SCHD) command must be issued. To maintain all statuses globally, the UPDATE TRAN command must be issued with all of the statuses in one command. The IMS systems in the IMSplex still contain the resource definitions. RM does not ensure resource definition consistency across the IMSplex. You can use global online change to update the resource definitions consistently in the IMS systems across the IMSplex. Serialized Program Management If you want to define an application program as a serial program (that is, it cannot be scheduled simultaneously into message or batch message regions) in an IMSplex environment that does not use shared queues, use the SCHDTYP=SERIAL parameter of the APPLCTN macro or in a CREATE PGM command. Serially-executing application programs cannot be scheduled to run simultaneously in more than one message or batch message region. Parallel application programs (SCHDTYP=PARALLEL), however, can be scheduled to run simultaneously. You can also define an application program as serial in an IMSplex environment with shared queues. Sysplex serialized program management allows users in a shared queues environment to prevent application programs that are defined as serial from being scheduled in parallel on another IMS system in an IMSplex. IMS automatically serializes the scheduling of application programs that are defined as serial under the following conditions: Shared queues is enabled. RM is active and has a resource structure defined. IMS is defined with GBL_SERIAL_PGM=YES (the default) Information about scheduled serial PSBs is maintained in the RM resource structure to ensure that the serial PSB is scheduled in only one IMS across an IMSplex at any point in time. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 11 of 19
Best Practice: Diagnose resource problems with QUERY commands Use type-2 QUERY commands to query resources that have a problem. QUERY commands offer more diagnostic information than type-1 commands, such as reason codes, completion codes, completion code text, error text, and NOTINIT status. Type-2 commands are so useful that you should consider using them for a simple monoplex (just one IMS system). The cost of the extra address spaces is worth the benefits for managing the system and resources. The QUERY command requires that SCI and OM be enabled, but it can be issued for resources defined using any method, including the system definition process, online change, and dynamic resource definition. If a transaction or program scheduling fails, a best practice is to issue QUERY DB, QUERY PGM, QUERY RTC and/or QUERY TRAN commands with SHOW(STATUS) to see the status of these resources and the relationships of the resources. Many problems can easily be corrected by looking at the resource status. For example, if a program or database shows a status of NOTINIT-xx-reason, where xx is the unique module reason why the resource is not initialized, you can look at the NOTINIT-xx-reason table in the IMS Command Reference to determine if the problem is one you can solve, or if you need to contact IBM Software Support. An example of a common error is a QUERY PGM NAME(pgmname) SHOW(STATUS) command that shows a status of NOTINIT-xx- NOPSB. NOPSB means that the application program is defined to IMS, but the PSB is not in the ACBLIB. You can correct this specific problem by running the ACB generation utility to add the PSB to the ACBLIB, then doing an online change for ACBLIB to make the changed ACBLIB active in IMS. QUERY commands can also be used to explore associations between referenced resources. Many transaction and program problems are related to the databases that they access. Here is a list of QUERY commands that show references: The QUERY TRAN SHOW(PGM) command displays the program that a specified transaction references. The QUERY RTC SHOW(PGM) command displays the program that a specified routing code references. The QUERY PGM SHOW(DB) command displays the databases that a specified program references. QUERY DB SHOW(PGM) command displays the programs that reference a specified database. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 12 of 19
Best practice: Use QUERY commands to identify work-in-progress before using online change You can use QUERY commands with the SHOW(WORK) parameter be used to find out if a resource has work-in-progress before an online change or UPDATE command is issued to modify the resource attributes. Resources with work in progress are blocked for changes, so you can reduce the chance of a conflict occurring by checking the status of the resource before starting an online change. When IMS is enabled with the IMS repository, the QUERY SHOW(DEFN) commands can be used to show the resource definitions in IMS and the repository. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 13 of 19
Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 14 of 19
Best practices Enable OM and SCI for type-2 commands Verify command return and reason codes in automated SPOC programs Enable global status in the IMSplex Issue single commands to set multiple statuses with global command status Diagnose resource problems with QUERY commands Use QUERY commands to identify work-in-progress before using online change Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 15 of 19
Conclusion IMS continues to move toward a model of resource management that is dynamic, centralized, and automated. This article gives an overview of the resource management methods in an IMSplex to help you make informed decisions about the best ways to manage resource definitions in your environment. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 16 of 19
Further reading Best practices: Creating, storing, and managing definitions for DOPT PSB and GPSB resources Best practices: Creating, storing, and managing definitions for IMS resources Information Management best practices: http://www.ibm.com/developerworks/data/bestpractices/ Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 17 of 19
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON- INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. Without limiting the above disclaimers, IBM provides no representations or warranties regarding the accuracy, reliability or serviceability of any information or recommendations provided in this publication, or with respect to any results that may be obtained by the use of the information or observance of any recommendations provided herein. The information contained in this document has not been submitted to any formal IBM test and is distributed AS IS. The use of this information or the implementation of any recommendations or techniques herein is a customer responsibility and depends on the customer s ability to evaluate and integrate them into the customer s operational environment. While each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will be obtained elsewhere. Anyone attempting to adapt these techniques to their own environment do so at their own risk. This document and the information contained herein may be used solely in connection with the IBM products discussed in this document. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 18 of 19
Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: Copyright IBM Corporation 2013. All Rights Reserved. This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol ( or ), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at Copyright and trademark information at www.ibm.com/legal/copytrade.shtml Windows is a trademark of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. Contacting IBM To provide feedback about this paper, write to imspubs@us.ibm.com To contact IBM in your country or region, check the IBM Directory of Worldwide Contacts at http://www.ibm.com/planetwide To learn more about IBM Information Management products, go to http://www.ibm.com/software/data/ Managing resources in an IMSplex using OM, type-2 commands, and SPOC page 19 of 19