MIMIX Monitor

MIMIX® Version 7.0 Using MIMIX Monitor Published: September 2010 level 7.0.01.00 Copyrights, Trademarks, and Notices 2 Contents Version 7.0 Using MIMIX Monitor Who this book is for..................................................................................................... 8 What is in this book............................................................................................... 8 The MIMIX documentation set .................................................................................... 8 SNA and OptiConnect Support Discontinued.............................................................. 9 Sources for additional information............................................................................. 10 How to contact us...................................................................................................... 11 Chapter 1 MIMIX Monitor overview 12 Monitor concepts....................................................................................................... 13 Components of a monitor.................................................................................... 13 Switching concepts.................................................................................................... 14 Support for switch automation............................................................................. 15 The MIMIX Model Switch Framework ................................................................. 16 Additional switch information............................................................................... 16 Monitor objects supplied with MIMIX......................................................................... 17 Basic operation.......................................................................................................... 20 Interface exit program processing....................................................................... 20 Master monitor .................................................................................................... 21 Monitor processing.............................................................................................. 22 Interval master monitor........................................................................................ 25 Group monitor processing................................................................................... 25 Additional switch definition operations ................................................................ 28 Chapter 2 Checklist: preparation 29 Security considerations ............................................................................................. 30 Preparing for a switch................................................................................................ 31 Requirements for switching................................................................................. 32 Starting the MIMIXSBS subsystem........................................................................... 33 Accessing the MIMIX Main Menu.............................................................................. 34 Chapter 3 Working with monitors 36 Starting and ending the master monitors .................................................................. 37 Starting the master monitor on the local system................................................. 37 Ending the master monitor on the local system.................................................. 37 Starting and ending the interval master monitor.................................................. 38 Displaying a list of monitors on a system.................................................................. 39 Actions available for monitors ............................................................................. 39 Monitor status values .......................................................................................... 40 Starting a monitor...................................................................................................... 42 Ending a monitor....................................................................................................... 43 Running condition and event programs for a monitor ............................................... 44 Enabling or disabling a monitor................................................................................. 45 Enabling a monitor .............................................................................................. 45 3 Disabling a monitor.............................................................................................. 45 Placing a monitor on hold.......................................................................................... 47 Releasing a held monitor........................................................................................... 48 Working with the message log.................................................................................. 49 Other operations available from a 5250 emulator..................................................... 50 Displaying monitor status details......................................................................... 50 Changing monitors .............................................................................................. 51 Copying monitors ................................................................................................ 51 Deleting a monitor ............................................................................................... 51 Displaying a monitor............................................................................................ 52 Printing a monitor ................................................................................................ 52 Renaming a monitor............................................................................................ 52 Working with information for a monitor................................................................ 52 Exporting and importing monitors........................................................................ 53 Exporting a monitor ....................................................................................... 53 Importing a monitor........................................................................................ 54 Working with monitor job logs ............................................................................. 55 Chapter 4 Creating user-defined monitors 57 Common parameters on the CRTMONOBJ command............................................. 57 Creating monitors...................................................................................................... 61 Creating a time monitor....................................................................................... 61 Tips for time monitors.................................................................................... 62 Creating a journal monitor................................................................................... 63 Creating a message queue monitor .................................................................... 65 Creating an interval monitor ................................................................................ 66 Creating a group monitor..................................................................................... 68 Event classes ............................................................................................................ 71 Predefined conditions for event classes and their associated parameters ......... 71 Interval monitors (*INTERVAL) ........................................................................... 72 When to use an interval monitor.................................................................... 73 J ournal monitors (*J RN)...................................................................................... 74 When to use a journal monitor....................................................................... 74 Extended journal monitors (*EXDJ RN) ............................................................... 75 Message queue monitors (*MSGQ) .................................................................... 75 When to use a message queue monitor........................................................ 76 Time monitors (*TIME) ........................................................................................ 76 When to use a time monitor........................................................................... 76 Group monitors (*GROUP).................................................................................. 77 When to use a group monitor........................................................................ 77 Predefined monitors (*PREDFN)......................................................................... 77 Chapter 5 Working with switch definitions 79 Accessing the Work with Switch Definitions display.................................................. 80 Creating switch definitions......................................................................................... 81 Creating a switch definition for TCP .................................................................... 81 Creating a switch definition for hardware switching ............................................ 82 Creating a switch definition for type *NONE........................................................ 83 Changing a switch definition...................................................................................... 85 Deleting a switch definition........................................................................................ 86 4 Displaying a switch definition.................................................................................... 87 Printing a switch definition......................................................................................... 88 Working with monitors for a switch definition............................................................ 89 Starting monitors for a switch definition............................................................... 89 Ending monitors for a switch definition................................................................ 89 Switching users manually.......................................................................................... 91 Synchronizing settings in the switching hardware............................................... 92 Displaying status for a switch definition..................................................................... 94 Running the event program for a switch definition.................................................... 95 Accessing the Work with Device Entries display....................................................... 96 Adding all devices to a switch definition.............................................................. 96 Adding a device entry.......................................................................................... 96 Changing a device entry...................................................................................... 96 Removing a device entry..................................................................................... 97 Displaying a device entry .................................................................................... 97 Printing a device entry......................................................................................... 97 Displaying and ending the switch screen.................................................................. 98 Displaying the switch screen............................................................................... 98 Ending the switch screen .................................................................................... 98 Changing the logon message during a switch..................................................... 98 Chapter 6 Using the MIMIX Model Switch Framework 100 Phases of switching in MIMIX Model Switch Framework........................................ 101 Operating requirements........................................................................................... 103 Securing your MIMIX Model Switch Framework environment................................. 104 MIMIX Model Switch Framework commands.......................................................... 105 Configuring an automated switch............................................................................ 106 About the RUNSWTFWK command....................................................................... 107 RUNSWTFWK success and failure indicators ........................................................ 108 Events and status: RUNSWTFWK command is invoked.................................. 109 Events and status: Starting a planned switch to a backup system.................... 109 Events and status: Starting an unplanned switch to a backup system.............. 110 Events and status: Starting the switch synchronization .................................... 111 Events and status: Returning to the production system.................................... 112 Enabling the MIMIX Model Switch Framework........................................................ 114 Disabling the MIMIX Model Switch Framework....................................................... 114 MIMIX Model Switch Framework messages ........................................................... 115 Completing a switch after encountering errors........................................................ 116 MIMIX Model Switch Framework status codes ....................................................... 117 MIMIX Model Switch Framework user exit programs.............................................. 121 Orphaned data and objects..................................................................................... 122 Chapter 7 Working with the UPS monitor 123 UPS monitor highlights............................................................................................ 124 Checklist: UPS configuration................................................................................... 126 Evaluating battery time requirements...................................................................... 127 Ensuring the UPS monitor is always active............................................................. 129 Setting system values for the UPS monitor............................................................. 130 Setting the job priority for the UPS monitor............................................................. 131 Accessing the UPS monitor menu........................................................................... 132 5 Configuring the UPS monitor................................................................................... 133 Changing warning message text............................................................................. 135 Starting and ending the UPS monitor...................................................................... 136 Testing the UPS configuration................................................................................. 137 Updating the available UPS power.......................................................................... 138 Testing power changes ........................................................................................... 139 Displaying status for the UPS monitor..................................................................... 141 Changing the UPS subsystem................................................................................ 143 Removing the UPS monitor from the controlling subsystem............................. 143 Chapter 8 Programming for monitors 144 Adding messages to the MIMIX message log......................................................... 145 What to include in your programs............................................................................ 146 Programming for switching................................................................................ 146 Programming for the UPS monitor .................................................................... 146 Interface exit program............................................................................................. 147 Required parameters......................................................................................... 147 Condition program................................................................................................... 149 Required parameters......................................................................................... 149 Event program......................................................................................................... 150 Required parameters......................................................................................... 150 MIMIX Monitor User Access API ............................................................................. 152 MMUSRACCS member..................................................................................... 152 Authorities and locks ......................................................................................... 152 Required parameters......................................................................................... 152 MON0100 format......................................................................................... 153 MON0200 format......................................................................................... 154 Field descriptions......................................................................................... 154 Additional data structures........................................................................................ 156 Detail information format................................................................................... 156 Message Queue (*MSGQ) ................................................................................ 156 Interval (*INTERVAL) ........................................................................................ 157 J ournal (*J RN)................................................................................................... 157 Time (*TIME)..................................................................................................... 158 Group (*GROUP) .............................................................................................. 158 Error code structure........................................................................................... 159 Field descriptions .................................................................................................... 160 Monitor program examples...................................................................................... 163 Interface exit program example......................................................................... 163 Condition program example.............................................................................. 164 Event program example.................................................................................... 165 Chapter 9 Resolving problems 167 Gathering information before reporting a problem.................................................. 168 Obtaining MIMIX and IBM i information from your system................................ 168 Appendix A MIMIX Monitor commands 169 MIMIX Monitor commands by group....................................................................... 169 Master monitor commands................................................................................ 169 Monitor commands............................................................................................ 169 Switch definition commands.............................................................................. 170 6 Switch device entry commands......................................................................... 170 MIMIX Model Switch Framework commands.................................................... 170 UPS monitor commands ................................................................................... 171 Appendix B Hardware switching devices 172 Hardware switch configurations .............................................................................. 173 Local configuration - SM900A switch................................................................ 173 Remote configuration........................................................................................ 174 Switching hardware requirements..................................................................... 174 Planning for switching hardware............................................................................. 177 Related communications procedures...................................................................... 180 Defining local communications.......................................................................... 180 Defining remote communications...................................................................... 181 For autodial V.25BIS modems..................................................................... 181 For other (non-autodial) modems................................................................ 182 Appendix C Work sheets for switching hardware 184 Work sheet A: rack cards and cables...................................................................... 184 Work sheet B: device and port assignments........................................................... 185 Work sheet C: port layout........................................................................................ 185 Appendix D Copying configuration data 187 Supported upgrade paths for copying configuration data........................................ 187 Checklist: copy monitor configuration data from a previous release....................... 187 Using the CPYCFGDTA command for MIMIX Monitor...................................... 187 Index 190 7 8 Who this book is for The Using MIMIX Monitor book is for MIMIX administrators who have a need to set up custom monitoring for a MIMIX environment or who need to support a switching environment which uses the MIMIX Model Switch Framework. What is in this book The Using MIMIX Monitor book identifies the monitors that are shipped with or created by MIMIX products and provides operational tasks for working with monitors. This book also describes monitoring concepts, procedures for creating user-defined monitors and provides programming information for creating exit programs to be called by monitors. This book also describes the switching environment provided by MIMIX Model Switch Framework, commands for using the switch framework, and the events and status indicators possible during each phase of a switch performed by a switch framework. This book also describes how to configure switch definitions to support hardware switching. The MIMIX documentation set The following documents about MIMIX products are available: Using License Manager This book describes software requirements, system security, and other planning considerations for installing MIMIX software and software fixes. The preferred way to obtain license keys and install software is by using AutoValidate and the MIMIX Installation Wizard. However, if you cannot use them, this book provides instructions for obtaining licenses and installing software from a 5250 emulator. This book also describes how to use the additional security functions from Vision Solutions which are available for MIMIX products and commands through License Manager. Also, to support compatible previous releases, this book includes requirements and troubleshooting information for MIMIX Availability Manager. MIMIX Administrator Reference This book provides detailed conceptual, configuration, and programming information for MIMIX Enterprise and MIMIX Professional. It includes checklists for setting up several common configurations, information for planning what to replicate, and detailed advanced configuration topics for custom needs. It also identifies what information can be returned in outfiles if used in automation. MIMIX Global Operations This book provides high level concepts and operational procedures for MIMIX Global users in an IBM i cluster environment. This book focuses on addressing problems reported in status and basic operational procedures such as starting, ending, and switching. MIMIX Operations - 5250 SNA and OptiConnect Support Discontinued 9 This book provides high level concepts and operational procedures for managing your high availability environment using MIMIX Enterprise or MIMIX Professional from a 5250 emulator. This book focuses on tasks typically performed by an operator, such as checking status, starting or stopping replication, performing audits, and basic problem resolution. Using MIMIX Monitor This book describes how to use the MIMIX Monitor user and programming interfaces available with MIMIX Enterprise or MIMIX Professional. This book also includes programming information about MIMIX Model Switch Framework and support for hardware switching. Using MIMIX Promoter This book describes how to use MIMIX commands for copying and reorganizing active files. MIMIX Promoter is available with MIMIX Enterprise only. MIMIX for IBM WebSphere MQ This book identifies requirements for the MIMIX for MQ feature which supports replication in IBM WebSphere MQ environments. This book describes how to configure MIMIX for this environment and how to perform the initial synchronization and initial startup. Once configured and started, all other operations are performed as described in the MIMIX Operations - 5250 book. SNA and OptiConnect Support Discontinued With the release of MIMIX V7.0, MIMIX no longer supports configurations using SNA or OptiConnect for communications. The parameters are still available within MIMIX version 7.0, however, this functionality will not be tested for MIMIX V7.0. Vision Solutions will only assist customers to determine possible workarounds with issues arising from the use of SNA or OptiConnect for communication in MIMIX V7.0. 10 Sources for additional information This book refers to other published information. The following information, plus additional technical information, can be located in the IBM System i and i5/OS Information Center. From the Information center you can access these IBM Power TM Systems topics, books, and redbooks: • Backup and Recovery • API Programming How to contact us 11 How to contact us For contact information, visit our Contact CustomerCare web page. If you are current on maintenance, support for MIMIX products is also available when you log in to Support Central. It is important to include product and version information whenever you report problems. MIMIX Monitor overview 12 CHAPTER 1 MIMIX Monitor overview MIMIX Monitor enables you to customize and control events in your MIMIX and IBM Power TM Systems environments. It is shipped and installed with MIMIX Enterprise and MIMIX Professional. Several monitors are shipped with MIMIX to perform specific functions within your MIMIX environment. MIMIX Monitor also provides the capability to create your own monitors to perform a specific action by triggering an event when a specified condition occurs on your system. Each monitor is characterized by an event class that you can use to watch for specific predefined conditions. This book describes the function of shipped monitors, how to perform system operations on monitors, and how to program your own monitors. This book also describes how to use features for switching that interact with the capabilities of MIMIX Monitor. You can use MIMIX Monitor to: • Aid in automating your Power TM Systems operations and processes. MIMIX Monitor can often eliminate your need to manually intervene when a specific condition occurs on your system. • Check the health of your production system and move the processes to a backup system when unplanned downtime occurs. • Off-load your production system during planned downtime. MIMIX Monitor can automate switching operations between your production system and your backup system. You can use MIMIX Monitor from a backup system with other equipment to switch hardware devices or software interfaces from a failed production system to the backup system. MIMIX Monitor determines the need to switch to a backup system by examining specific objects in a configuration that indicate the status of the production environment or an interface to determine when switching to a backup system is necessary. You can also use this configuration for planned switching. These objects may or may not indicate the health of a production system. When the object cannot be recovered, condition and event programs start the actions you want to perform. When you use this capability in a switching operation, you can have multiple monitors examining different conditions. When all of these conditions occur, this can trigger a switch from your production system to your backup system. Monitor concepts 13 Monitor concepts MIMIX Monitor manages the following types of monitors: • Monitor objects supplied with MIMIX • User-defined monitor objects • Third party-supplied monitor objects All monitor objects identify a condition and wait for it to occur on the system. When a monitor object detects the condition, it causes the system to take action as specified in the event program. MIMIX Monitor enables you to customize monitor objects to the workflow and environment of your enterprise. You can define monitors to run immediately, continually, at scheduled intervals, or after a particular event. You can group monitor objects together to coordinate activity among multiple monitor objects and to control switching operations. Components of a monitor You can define a monitor for just about anything. When you define a monitor, you are creating a monitor object. The monitor object identifies the: • Event class • Information that defines the event • Programs to call when the event occurs Event classes are predefined conditions that trigger running programs associated with a monitor. Each monitor object identifies an event class (EVTCLS parameter) and a set of parameters that defines the event. This set of parameters that define the event is referred to as the predefined condition. For example, the predefined condition for a time monitor includes the time of day and the day or date to run the specified programs. MIMIX Monitor supports monitor objects based on the following event classes: *INTERVAL, *J RN, *EXDJ RN, *MSGQ, *TIME, *GROUP, and *PREDFN. For more information, see “Event classes” on page 71. In addition to the event class and the parameters that define it, each monitor object must have one or more of the following programs: • Condition program • Event program • Interface exit program Although each type of program is optional, every monitor must have either a condition program or an event program before the monitor can be started. If you create a monitor to use only an interface exit program, your program needs to control all operations of the monitor, including running the monitor. The condition program defines the system or program activities to be performed and is called when the predefined conditions are met. The condition program can be used 14 to check additional conditions before the event program is run. Any additional conditions to check that are included in the condition program are referred to as user- defined conditions. If you do not specify a condition program, the monitor will call the event program without any further conditional checking. The event program defines the event or action to initiate when the conditions (both predefined and user-defined) occur. An event program is used to handle the triggered event by taking some user-defined action. When you use a monitor in a switching scenario, the event program contains your switching commands and program calls. The interface exit program provides an optional way of associating additional programming or information with a monitor. Except where noted, the interface exit program is called before (pre-exit) and after (post-exit) each requested operation for a monitor object. In effect, an interface exit program can determine which operations (either selecting an option on a display or running a command) will be processed for a monitor and what activities will occur before and after the requested option is processed. Additional displays that may require a response could be programmed to appear before or after you see the display for the selected option. For more information, see the following topics in the chapter “Programming for monitors” on page 144 • “What to include in your programs” on page 146 • “Condition program” on page 149 • “Event program” on page 150 • “Interface exit program” on page 147 Switching concepts Switching is commonly used to maintain high availability and prevent unplanned downtime. Planned switches can also be performed for system maintenance, backups, or for workload balancing. Two features of MIMIX can assist you with switching in a MIMIX environment: • Switch definitions for automating and customizing switching. Switch definitions permit the customization of your switching environment. Switch definitions identify the participating systems, the devices, applications, commercially available switching hardware, or TCP/IP addresses to be switched, and an event program containing your customized switching program. A group monitor associated with the switch definition provides the capability of defining multiple events that will participate in the decision to switch. • MIMIX Model Switch Framework. The MIMIX Model Switch Framework provides a consistent framework for performing planned or unplanned switches through a set of commands and programs. MIMIX Model Switch Framework is the basis on which newer, simplified switching user interfaces operate, such as the MIMIX MIMIX Switch Assistant ™ interface within MIMIX Availability Manager. Typically, a Certified MIMIX Consultant assists you in setting up the programs and the switching environment. Switching concepts 15 These features can be used individually or in combination. For example, a switch definition can be defined to a MIMIX Model Switch Framework. The switch framework processing will handle initiating switching for the hardware or IP impersonation defined by the switch definition. Optionally, the SETSWTSRC command for the switch definition can be performed by the MIMIX Model Switch Framework event program. If this case, do not specify the switch definition for the Switch definition (SWTDFN) parameter when creating the switch framework definition with the CRTSWTFWK command. Support for switch automation MIMIX Monitor manages switch definitions that can be used with monitor objects to enable automated switching between two systems. This switching support enables you to customize: • What monitored objects participate in a decision to switch from a production system to a backup system. • How the switch will be performed. • Which devices or applications will be switched. When you use a monitor in a switching scenario, MIMIX Monitor uses a switch definition in which you identify: • The systems participating in the switch. • The parameters associated with how the switch is controlled. • The event program that contains your customized switching programming. The switch definition can specify commercially available switching hardware or TCP/IP address impersonation. The event program identifies and controls what is switched between systems. You can switch users, applications, and hardware devices. When used with MIMIX replication processes, you can switch the direction of replication within MIMIX by including the appropriate MIMIX commands. When the switch definition is created, a group monitor (event class *GROUP) is automatically created to control the switch definition. The group monitor has the same name as the switch definition and will call the event program specified in the switch definition. While the group monitor controls the switch, any combination of monitor objects can participate in the decision to switch. When the participating monitor objects all agree at a point in time that the objects they are monitoring have failed, the group monitor is triggered to run the switching software. This is usually done by using the Run Switch Framework (RUNSWTFWK) command in the group monitor’s event program. To form the association between a participating monitor and a group monitor, the name of the group monitor is used as the value of the monitor group parameter (MONGRP) on the participating monitor. Any active monitor that has the group monitor name specified for this parameter will participate in the decision to trigger the switch. 16 Participating monitor objects can be created to watch and attempt recovery on failed lines, controllers, or devices that communicate with the production system. TCP/IP interfaces and OptiConnect/400 connections that are defined through a transfer definition can also be monitored to ensure that they remain active. Other objects such as message queues or journals can also be monitored if there are messages or transactions that might be appropriate to cause the triggering of a switch. When all participating monitor objects have failed because these objects cannot be recovered, are not communicating, or have received a message or a transaction that indicates the necessity for switching, the group monitor triggers the events necessary to switch users and applications to the backup system. MIMIX Monitor also supports the ability to identify devices to a switch definition so you can display messages about the status of the system during the switch. The MIMIX Model Switch Framework The MIMIX Model Switch Framework is a set of programs and commands designed to provide a consistent framework for performing and controlling planned or unplanned switches in a MIMIX environment. The MIMIX Switch Assistant user interface is based on having a default MIMIX Model Switch Framework defined. The MIMIX Model Switch Framework programs will enable you to more easily create the switch code by standardizing the portions of code required to switch the MIMIX environment. The only code that will need to be written will be the code for the programs that alter the customer’s environment, such as starting or ending production. Additional switch information If you plan to use MIMIX features for switching, before you begin you should read “Preparing for a switch” on page 31 and “Requirements for switching” on page 32. Two chapters in this book provide detailed information about switching support. • “Working with switch definitions” on page 79 describes how to create and work with switch definitions. • “Using the MIMIX Model Switch Framework” on page 100 provides detailed information about creating a default switch framework. A switch framework is the basis for user interfaces such as MIMIX Switch Assistant. Monitor objects supplied with MIMIX 17 Monitor objects supplied with MIMIX MIMIX Enterprise and MIMIX Professional are shipped with a number of ready to use monitor objects that meet a specific need. These monitors can be triggered by any form of event class and may or may not enable you to customize them to your needs. These monitors may also include their own additional menus, commands, and displays. The UPS monitor is shipped with MIMIX Monitor. You can use the UPS monitor to check on the status of an uninterruptible power supply. “Working with the UPS monitor” on page 123 provides an overview of the UPS monitor and describes how to configure it. Two remote journal link monitors are created automatically by the MIMIX Remote J ournal support within MIMIX Enterprise or MIMIX Professional for each defined remote journal. Their function is to monitor the journal message queues, one on the source system and one on the target system for the specified remote journal. These monitors provide added value to MIMIX user journal replication processes by allowing MIMIX to automatically monitor the state of the remote journal link, to notify the user of problems, and to automatically recover the link when possible. For more information, see the MIMIX Administrator Reference book. The MIMIX AutoNotify ™ feature within MIMIX Enterprise or MIMIX Professional uses the shipped monitor for new object notification entries, MMNFYNEWE, to monitor the source system in a replication environment. The AutoNotify feature makes it easier to identify new objects in your production environment that may need to be replicated. The MMNFYNEWE monitor is a journal monitor that watches the security audit journal (QAUDJ RN) for newly created libraries, folders, or directories that are not already included or excluded for replication by a data group and sends warning notifications when its conditions are met. This monitor is shipped disabled. User action is required to enable this monitor on the source system within your MIMIX environment. Once enabled, the monitor will automatically start with the master monitor. For more information about the conditions that are checked, see the MIMIX Operations book. The independent ASP threshold monitor, MMIASPMON, is shipped with MIMIX Enterprise and MIMIX Professional and will notify you when an independent ASP threshold is exceeded. This monitor improves the capability for detecting potential independent ASP overflow conditions that put your high availability solution at risk due to insufficient storage. This monitor checks the QSYSOPR message queue in library QSYS for messages indicating that the amount of storage used by an independent ASP exceeds a defined threshold. When this condition is detected, the monitor sends a warning notification that the threshold is exceeded. The status of warning notifications is incorporated into overall MIMIX status. The independent ASP threshold monitor is shipped disabled. If you want to use this monitor, user action is required to enable it on all systems in the MIMIX installation that are using independent ASPs. Note: Each ASP defaults to 90% as the threshold value. To change the threshold value, you must use IBM's iSeries Navigator. 18 Two or more PAPM monitors run on the target system of each data group for which the parallel access path maintenance function has been enabled and activated. The monitors are created and started on the target system as a result of running the Start Data Group (STRDG) command for a data group after the function has been enabled by setting the parallel access path maintenance policy. The policy can be set for the installation or for a specific data group. The following monitors are associated with this function: • The parallel access path maintenance group monitor (short-data-group- name_PAPM) provides ease of control over associated monitors that perform parallel access path maintenance for a data group. • When this monitor exists, there are always associated monitors of one of the following types: – The parallel access path maint monitor nnn (short-data-group-namePAPMnnn) monitors are created and used for the automatic method of performing parallel access path maintenance for a data group. The value of nnn identifies a unique monitor, with values ranging from 000 through 999. The number of monitors is determined by the policy setting. – The parallel access path maint monitor job-name (short-data-group- nameJobname) monitors are created and used for the manual method of performing parallel access path maintenance for a data group. The Jobname identifies a unique monitor as determined by the policy setting and the configuration file. Monitors associated with MIMIX Global The following monitors are associated with MIMIX Global. One or more may be present, depending which license keys are present. • The application group status monitor is created when an application group definition is created and has the same name as the application group. This monitor sends a notification if the application group has any status values of *ATTN. Logical replication status is not checked or reported as other mechanisms exist for reporting replication status problems. • The switch delay monitor is created when a device CRG is created and has the same name as the device CRG. This monitor sends notifications when conditions exist that may require action to prevent a prolonged switch. Notifications are sent when there are differences in UID values or in GID values between the primary and backup nodes, when the number of independent ASP libraries falls below the value specified in the independent ASP ratio policy, and when a library exists in the ASP group of the switchable independent ASP on the primary node and also exists in SYSBAS on the backup node. • The cluster administration domain monitor, named #MCADMDMN, periodically checks for new objects to be added to the IBM cluster administrative domain. The monitor will add a Monitored Resource Entry to the administrative domain for all objects that have been found. • The cluster SAN connection monitor, named MCSANCNN, is automatically created when the first data resource group of type of *PPRC or *LUN is created. Monitor objects supplied with MIMIX 19 The monitor watches the QSYSOPR message queue for message CPPEA02 (*Attention Contact your hardware service provider now) which indicates there is a potential problem with the fiber channel connection between the node and the SAN storage device. If CPPEA02 is issued on a backup node and is not noticed, that node can be adversely affected and the independent ASP associated with the *LUN or *PPRC data resource group will not be able to switch to that backup node. When the monitor detects message CPPEA02, it sends a notification to inform you of the potential problem. The monitor is created on each node associated with a data resource group and has a value of *NO for Start with master monitor (AUTOSTR). To ensure that the Cluster SAN connection monitor will automatically start and end with the master monitor on a system, the AUTOSTR value must be changed to *YES. 20 Basic operation MIMIX Monitor uses two specialized monitors to control and maintain all other monitors except for the UPS monitor. These two controlling monitors, the master monitor and the interval master monitor, are largely transparent to users. Each monitor, including the master monitor, operates on a single system. Some shipped monitors, such as those used by MIMIX AutoGuard™, are provided on each system in an installation but only run on the system permitted by policy settings. MIMIX Availability Manager provides operational support for monitors. Operational support and support for configuring user-defined monitors is available from a 5250 emulator from the Work with Monitors display. User interaction with switch definitions occurs primarily through its associated group monitor, or through the Work with Switch Definitions display from a 5250 emulator. “Using the MIMIX Model Switch Framework” on page 100 identifies the preferred user interfaces and describes MIMIX Model Switch Framework operation. Interface exit program processing When any operation is requested for a monitor by invoking a command or by taking an option from a user interface, if an interface exit program exists it is called as a pre- call to the operation. If the program is successful the requested operation on the monitor is processed. If the operation is successful, the interface exit program is called as a post-call to perform any additional user-specified processing. Figure 1 shows this operation. Basic operation 21 Figure 1. Interaction with interface exit program. “Working with monitors” on page 36 describes the operations that you can perform on monitors. “Programming for monitors” on page 144 describes the programming requirements for the condition, event, and interface exit programs identified in a monitor. Master monitor Each system in a MIMIX environment has a master monitor that is used to control and maintain all other monitors on that system. The master monitor is a job in the MIMIXSBS subsystem that is automatically started when the subsystem is started as long as the autostart job entry that was added during installation has not been removed. The master monitor runs in the background. If the master monitor job ends because of an unexpected error or termination, the master monitor attempts to restart itself. The Start MIMIX (STRMMX) and End MIMIX (ENDMMX) commands also include the master monitor jobs along with other MIMIX processes. The STRMMX and ENDMMX commands are the preferred method of ending all MIMIX activity within an installation. If the master monitor is not already active, it will be started when there is a request to start any other monitor. When a request to start the master monitor is processed, MIMIX also starts any monitors that specify *YES for the Start with master monitor (AUTOSTR) that are in a Interface Exit Program Pre-Call Requested Action Procesed Interface Exit Program Post-Call Entry Point This can be a request from a command, an option taken from a Work with panel, or a call from a program. Successful RC=0 Successful Failure RC=1 RC=0 or RC=1 22 status that permits them to be started. The master monitor also starts the interval master monitor when the first asynchronous interval monitor (*INTERVAL) is started. If you end the master monitor, all monitors are ended, but can be restarted. If the MIMIXSBS subsystem is inactive, you cannot start any monitor. Requests to start a monitor are queued and will process as soon as the subsystem is started. With the exception of the UPS monitor, the master monitor starts and ends all other monitors according to their configuration and status values, tracks which monitors should be kept active, and restarts those monitors if necessary. When the master monitor receives a request to start a monitor, the master monitor will start a job to perform the monitor processing. The master monitor determines if the last monitored event ran successfully and can instruct a monitor to end based on the status of the event. The master monitor also maintains control of *TIME and *GROUP monitors until they are triggered. Monitor processing MIMIX Monitor supports retry attempts for interval monitor objects, message queue monitor objects, and journal monitor objects that use synchronous processing. When a monitor is defined to use retry attempts, the conditions for which you are monitoring must be met the number of times that you specify before the event program is called. “Common parameters on the CRTMONOBJ command” on page 57 describes retry processing in more detail. MIMIX Monitor supports both synchronous and asynchronous processing of monitor activity. In synchronous processing, the monitor begins watching for the predefined condition. When it occurs, the condition program is called. When the user-defined conditions in the condition program are met, if the type of monitor supports retry attempts, the monitor restarts the cycle of waiting for the predefined condition to occur and meeting the user-defined conditions. The retry attempts cycle is complete when the predefined conditions and user-defined conditions are met for the specified number of retry attempts. When the specified number of retry attempts are completed, the monitor's event program is called. When the event program completes, the monitoring process is started again. Figure 2 shows this operation. Basic operation 23 Figure 2. Synchronous processing. MIMIX Monitor supports asynchronous processing for interval monitor objects, message queue monitor objects, and journal monitor objects. With asynchronous processing, the monitor watches for the predefined condition and starts a separate process to handle running the condition and event programs. This enables the monitor to start another cycle of watching for the predefined condition before MIMIX Monitor completes the processing associated with the previous cycle. Figure 3 shows this operation. 24 Figure 3. Asynchronous processing. Basic operation 25 Interval master monitor When the first interval monitor that uses asynchronous processing is started, the master monitor starts a job for the interval master monitor. The interval master monitor controls all monitoring for monitor objects that are classified as asynchronous interval monitors by maintaining a time counter and submitting jobs. If the interval master monitor ends abnormally, the master monitor is notified. The master monitor resubmits the job for the interval master monitor. If the interval master monitor ends or restarts, the time counter is reset to 0 at the time the interval master monitor starts and jobs are submitted based on this value. The interval master monitor maintains a list of interval monitors using asynchronous processing that have an active status. The interval master monitor checks for monitors that should be ended and removes them from the list. The interval master monitor determines the minimum amount of time to wait for each active monitor before submitting a separate job to run the condition and event programs specified for the monitor. If the condition is met, the event program specified for the monitor is run. The job tracks the status of the programs and updates the status for the monitor. If the job ends abnormally, the interval master monitor is notified. The interval master monitor determines if the job needs to be restarted. The interval master monitor receives notification of user requests to start or end an asynchronous interval monitor. Based on the result of the previous run of a monitor, the interval master monitor determines if the monitor should be run for subsequent intervals or if it should be ended. Group monitor processing A monitor is a member of a group when the value specified on its Monitor group parameter (MONGRP) matches the name of an existing group monitor (a monitor of event class *GROUP). When a start is requested for a group monitor, by default, all monitors in the group with a status of INACTIVE or FAILED are started. When a group monitor is active, all monitors in the group participate in the decision to run the group monitor's condition and event programs. Monitors with a DISABLED status are not considered active. DISABLED monitors do not participate in requests to start all monitors in the group and do not participate in decisions for the group monitor. However, DISABLED monitors can still be started individually. Once started, their status changes and the monitors will then participate in the triggering decision for the group. Monitors are considered active if their status is ACTIVE, SCHEDULED or, HELD. The transitional statuses of STARTING and ENDING are also considered active. FAILED/ACT is also considered active but, because its programs have experienced an error, the group monitor recognizes this as a failed monitor. Monitors with a status of INACTIVE can become active again if they are started individually. Any state change of a monitor participating in a group causes the group monitor to check the statuses of its participants. The group monitor remains active and does not consider running its programs until after the status of the last active monitor changes to INACTIVE, FAILED, or FAILED/ACT. If the last monitor ends successfully 26 (becomes INACTIVE) and the others are INACTIVE or DISABLED, the group monitor is ended (set to INACTIVE). If the last monitor fails (FAILED or FAILED/ACT), or if it ends successfully but one of the other monitors failed, the group monitor is triggered. The event program for a group monitor associated with a switch definition should be customized to run the commands necessary to switch the hardware, devices, or IP addresses identified in the switch definition. Basic operation 27 Figure 4. Group monitor processing 28 Additional switch definition operations MIMIX Monitor provides a command (Set Switch Source) that can be added to the event program called by the group monitor. This command will switch the hardware or software specified in the switch definition. If the switch definition specifies a switch type of *SM517A, a remote gang switch controller is used to switch a set of rack chassis with physically attached hardware from one system to another. If the switch type is *TCP, the TCP/IP interface specified is stopped on the production system and started on the backup system so that users accessing the production system through that interface are switched to the backup system. The Work with Switch Definition display and its commands enable you to create, change, delete, display, start, and end a switch definition. You can also set which system will be the source of data when the switch occurs, access the monitors associated with the switch definition, display status, run the condition and event programs associated with the switch definition, and work with device entries associated with the switch definition. The commands on the Work with Switch Device Entries enable you to assign devices to a switch definition so the event program notifies users at these devices of the status of the system during the switch. 29 CHAPTER 2 Checklist: preparation You should consider where MIMIX Monitor could help you in meeting your availability management requirements. Because MIMIX Monitor is typically used within a MIMIX installation, much of your planning and preparation should be considered in the context of your total MIMIX environment. Do the following to prepare to use MIMIX Monitor: 1. If you have not already done so, install and configure your MIMIX Enterprise or MIMIX Professional environment. 2. MIMIX Monitor uses the MIMIXOWN profile that is shipped with authority to all objects. To protect your systems from misuse, implement additional security processes based on the information in “Security considerations” on page 30. 3. If you have not already done so, turn on product-level security and grant authority to user profiles to control access to the MIMIX products. The Using License Manager book documents these tasks. 4. If you are updating an existing version 7 installation of MIMIX, review any critical monitors and verify that their status is correct. 5. Ensure that any system definitions and transfer definitions you will need for a monitor are configured for the MIMIX replication environment. Refer to the MIMIX Administrator Reference book. 6. If it is not already active, start the MIMIX subsystem using “Starting the MIMIXSBS subsystem” on page 33. 7. If you plan to use the UPS monitor, you need to configure the monitor. You may want to customize certain operations using the “Checklist: UPS configuration” on page 126. 8. If you plan to use the switching support within MIMIX Monitor, use topic “Preparing for a switch” on page 31 to guide you in preparing the systems for switching, creating a switch definition and an event program, and reviewing and testing your switching procedures. 9. Create any monitors you need that are not shipped with MIMIX. If you need user- defined monitors, you need to create monitors and the programs called by each monitor. For more information refer to “Working with monitors” on page 36 and “Programming for monitors” on page 144. 30 Security considerations Monitors within MIMIX Monitor run under the MIMIXOWN user profile which is shipped with special authority to all objects (*ALLOBJ ). When you create a monitor, the user profile creating that monitor must have authority to the interface exit program, condition program, or event program that is defined to the monitor MIMIX Monitor. *ALLOBJ authority is needed for MIMIX Monitor so that it has access to all objects that will be monitored, such as journals and message queues, the job scheduler, and any interface exit programs, condition programs, and event programs called by the monitor. If you are using MIMIX Switch Assistant or a MIMIX Model Switch Framework to switch the direction of replication and you changed the authority level of the MIMIXOWN user profile, the MIMIXOWN user profile needs to be granted explicit authority to the following: • Any custom user programs. • All MIMIX libraries to be switched. • Any communications configurations to be switched. • Change authority (*CHANGE) to the output queues of user profiles submitting switching commands so that MIMIX can write to spooled files. For more information about security considerations with the MIMIXOWN user profile, refer to topic ‘Security for MIMIXOWN user profile’ in the Using License Manager book. Preparing for a switch 31 Preparing for a switch If you plan to use the switching functions within MIMIX Monitor, you will need to do the following: 1. Verify that you have all the requirements for switching. See “Requirements for switching” on page 32. 2. If you plan to use MIMIX Monitor to control a hardware switching device, ensure that the hardware is installed. 3. Create a switch definition for the switch using the topic “Creating switch definitions” on page 81. The switch will automatically create a group monitor that is used for managing the switching operations you define in an event program. If you are doing IP impersonation and hardware switching you will need two switch definitions. The IP impersonation switching is usually done by specifying the IP switch name to the MIMIX Model Switch Framework definition. If you are using MIMIX Model Switch Framework to perform IP impersonation and hardware switching the event program of the group monitor will need to issue the RUNSWTFWK command. You will also need to change the event program to issue the SETSWTSRC command for the hardware switch definition. If you are using MIMIX Model Switch Framework and the switch definition is defined to the switch framework, the SETSWTSRC command is automatically done for you. 4. Define, to the switch definition, any devices that you want to allocate during the switch and display a message to users. Use either of the following topics: • “Adding all devices to a switch definition” on page 96 • “Adding a device entry” on page 96 5. Create additional monitors that will be associated with the group monitor and which will participate in the decision to trigger the event program containing your switching operations. Refer to “Creating monitors” on page 61. Notes: • The name of the switch definition is used for the group monitor and to form the association with other participating monitors. Use this name as the value for the Monitor group (MONGRP) parameter on the participating monitors. • To monitor a communications object (line, controller, or device), create an interval monitor with a subclass of *CFG. • To monitor a TCP/IP interface, create an interval monitor with subclass *TCP. 6. Create all of the following programs that you need using “Programming for monitors” on page 144. a. The event program defined to the switch definition (and in the group monitor). This program should contain any commands and calls to programs that you need to perform the switch. b. If needed, a condition program and interface exit program for the group monitor. 32 c. Additional condition programs and event programs you need for any monitors that will participate in the decision to trigger the group monitor's condition and event programs. d. Any interface exit programs you need for any of the participating monitors. 7. Verify that the participating monitors function as you require. 8. Schedule time to perform a test of the switching operation. Note: To automate your switch process, refer to “Using the MIMIX Model Switch Framework” on page 100. Requirements for switching To use MIMIX Monitor to perform switching, you need the following: • Two or more IBM Power TM Systems, or partitions; one system must be designated as a backup system. • Communications facilities between the production system and a backup system. If you have more than one production system to switch to the backup, each production system must have communication facilities between it and the backup system. Additionally, when a switch occurs you will still need to maintain a communications channel that MIMIX can use that is not affected by the switch. • MIMIX Enterprise or MIMIX Professional must be installed. Refer to the Using License Manager for the system and software requirements for these products and details about where you need these products installed. • System definitions and transfer definitions configured for the replication environment. If MIMIX is not already configured, you can use the MIMIX Administrator Reference book to help you. • Configuration dependent equipment. • Switching hardware (optional). If you plan to use MIMIX Monitor to control a hardware switching device, refer to “Planning for switching hardware” on page 177. • MIMIX Model Switch Framework also requires that a switch framework be configured. For more information, see “Operating requirements” on page 103. Starting the MIMIXSBS subsystem 33 Starting the MIMIXSBS subsystem By default, all MIMIX products run in the MIMIXSBS subsystem that is created when you install the product. This subsystem must be active before you can use the MIMIX products. If the MIMIXSBS is not already active, start the subsystem by typing the command STRSBS SBSD(MIMIXQGPL/MIMIXSBS) and pressing Enter. Note: You can ensure that the MIMIX subsystem is started after each IPL by adding this command to the end of the startup program for your system. Due to the unique requirements and complexities of each MIMIX implementation, it is strongly recommended that you contact your Certified MIMIX Consultant to determine the best way in which to design and implement this change. 34 Accessing the MIMIX Main Menu The MIMIX command accesses the main menu for a MIMIX installation. The MIMIX Main Menu has two assistance levels, basic and intermediate. The command defaults to the basic assistance level, shown in Figure 5, with its options designed to simplify day-to-day interaction with MIMIX. Figure 6 shows the intermediate assistance level. The options on the menu vary with the assistance level. In either assistance level, the available options also depend on the MIMIX products installed in the installation library and their licensing. The products installed and the licensing also affect subsequent menus and displays. Accessing the menu - If you know the name of the MIMIX installation you want, you can use the name to library-qualify the command, as follows: Type the command library-name/MIMIX and press Enter. The default name of the installation library is MIMIX. If you do not know the name of the library, do the following: 1. Type the command LAKEVIEW/WRKPRD and press Enter. 2. Type a 9 (Display product menu) next to the product in the library you want on the Lakeview Technology Installed Products display and press Enter. Changing the assistance level - The F21 key (Assistance level) on the main menu toggles between basic and intermediate levels of the menu. You can also specify the the Assistance Level (ASTLVL) parameter on the MIMIX command. Figure 5. MIMIX Basic Main Menu MIMIX Basic Main Menu Syst em: SYSTEM1 MI MI X Sel ect one of t he f ol l owi ng: 1. Wor k wi t h appl i cat i on gr oups WRKAG 2. St ar t MI MI X 3. End MI MI X 4. Swi t ch al l appl i cat i on gr oups 5. St ar t or compl et e swi t ch usi ng Swi t ch Asst . 6. Wor k wi t h dat a gr oups WRKDG 10. Avai l abi l i t y st at us WRKMMXSTS 11. Conf i gur at i on menu 12. Wor k wi t h moni t or s WRKMON 13. Wor k wi t h messages WRKMSGLOG 14. Cl ust er menu Mor e. . . Sel ect i on or command ===>__________________________________________________________________________ ______________________________________________________________________________ F3=Exi t F4=Pr ompt F9=Ret r i eve F21=Assi st ance l evel F12=Cancel ( C) Copyr i ght Vi si on Sol ut i ons, I nc. , 1990, 2010. Accessing the MIMIX Main Menu 35 Note: On the MIMIX Basic Main Menu, options 5 (Start or complete switch using Switch Asst.) and 10 (Availability Status) are not recommended for installations that use application groups. Figure 6. MIMIX Intermediate Main Menu MIMIX Intermediate Main Menu Syst em: SYSTEM1 MI MI X Sel ect one of t he f ol l owi ng: 1. Wor k wi t h dat a gr oups WRKDG 2. Wor k wi t h syst ems WRKSYS 3. Wor k wi t h messages WRKMSGLOG 4. Wor k wi t h moni t or s WRKMON 5. Wor k wi t h appl i cat i on gr oups WRKAG 6. Wor k wi t h audi t s WRKAUD 7. Wor k wi t h pr ocedur es WRKPROC 11. Conf i gur at i on menu 12. Compar e, ver i f y, and synchr oni ze menu 13. Ut i l i t i es menu 14. Cl ust er menu Mor e. . . Sel ect i on or command ===>__________________________________________________________________________ ______________________________________________________________________________ F3=Exi t F4=Pr ompt F9=Ret r i eve F21=Assi st ance l evel F12=Cancel ( C) Copyr i ght Vi si on Sol ut i ons, I nc. , 1990, 2010. Working with monitors 36 CHAPTER 3 Working with monitors This section describes how to perform day-to-day operations for monitors. MIMIX Availability Manager provides support for day-to-day operation of monitors. Through a 5250 emulator, the Work with Monitors display also provides operational support for monitors, including less frequently used operations, as well as configuration support. Some shipped monitors, such as the UPS monitor, may include additional menus and commands. “Working with the UPS monitor” on page 123 describes additional function that is unique to the UPS monitor. Starting and ending the master monitors 37 Starting and ending the master monitors In a MIMIX environment, there is a master monitor job on each system that controls all other monitors on the same system. The master monitor job runs in the MIMIXSBS subsystem. When the MIMIXSBS subsystem is started on a system, the master monitor job automatically starts on that system as long as the autostart job entry created during installation remains in the subsystem. If the master monitor is ended, starting any monitor will start the master monitor. The Start MIMIX (STRMMX) and End MIMIX (ENDMMX) commands also address the master monitor jobs along with other MIMIX processes. The STRMMX and ENDMMX commands are the preferred method of starting and ending all MIMIX activity within an installation. The STRMMX command will start all master monitors on all systems in a MIMIX installation. In turn, the master monitor on each system will start all monitors that are not disabled and which are configured to automatically start with the master monitor. The ENDMMX command will end all monitors that are in an active state. Then, the master monitor on each system is ended. You may also need to start or end a master monitor independently of other MIMIX jobs. You can do so from either MIMIX Availability Manager or from a 5250 emulator. The master monitor also starts the interval master monitor when the first asynchronous interval monitor is started. There is no way to directly interact with the interval master monitor. Starting the master monitor on the local system The master monitor will attempt to restart itself a limited number of times when it ends because of an error or if the job is abnormally ended. If an error condition prevents the master monitor from restarting itself, the master monitor will end. This causes all other active monitors, except for the UPS monitor, to also end. When the master monitor is started, other monitors that are configured to start with the master monitor and which are not disabled are started. From MIMIX Availability Manager, do the following to start the master monitor: 1. Select Monitors from the Details area in the navigation bar. 2. The master monitor is first monitor in the list displayed on the Monitors window. Select the Start action and click . 3. The Start Master Monitor window opens. Click OK. From a 5250 emulator, the master monitor does not appear in the list shown on the Work with Monitors display. Use the following command, specifying the name of the MIMIX installation library: installation-library/ STRMSTMON The master monitor job name will be the installation library name when it is started. Ending the master monitor on the local system You may need to end the master monitor when cleaning up the runtime environment, or when a CustomerCare representative directs you to end the master monitor. 38 Ending the master monitor also causes all other active monitors, except for the UPS monitor, to end. These monitors, including the interval master monitor, will not function correctly without the master monitor. From MIMIX Availability Manager, do the following to end the master monitor: 1. Select Monitors from the Details area in the navigation bar. 2. The master monitor is first monitor in the list displayed on the Monitors window. Select the End action and click . 3. The End Master Monitor window opens. Click OK. From a 5250 emulator, the master monitor does not appear in the list shown on the Work with Monitors display. Use the following command, specifying the name of the MIMIX installation library: installation-library/ ENDMSTMON Starting and ending the interval master monitor There is no direct way for you to control the interval master monitor. The interval master monitor is started automatically by the master monitor when an asynchronous interval monitor starts. If you need to start or end the interval master monitor, you can do so by starting or ending the master monitor. You can also end the interval master monitor by specifying MONITOR(*ALL) on the ENDMON (End Monitor) command. Displaying a list of monitors on a system 39 Displaying a list of monitors on a system From MIMIX Availability Manager, select Monitors from the Details area in the navigation bar. The list of monitors shown on the Monitor window includes the master monitor as the first monitor listed. The master monitor is followed by shipped monitors and user-defined monitors that are sorted by status, then by name. From a 5250 emulator, select option 12 (Work with monitors) from the MIMIX Basic Main Menu and press Enter. The list of monitors shown on the Work with Monitors display does not include the master monitor. Predefined monitors may be restricted to using a subset of the available options. Actions available for monitors The status of a monitor determines what actions you can perform on a monitor. Table 1 lists the status values required for each action and indicates where the action can be performed. Table 2 describes the status values. Table 1. Required status values for actions on monitors Action Available From Required Status Value (5250 emulator nomenclature) MIMIX Availability Manager 5250 emulator Create Yes Change Yes Inactive or Disabled Copy Yes Delete Yes Inactive, Failed, or Disabled Display Yes Print Yes Rename Yes Inactive, Failed, or Disabled Start Yes Yes Inactive, Failed, or Disabled End Yes Yes Active, Scheduled, Held, or Failed/Act Work with a Yes Status (details) Yes Hold Yes Yes Active or Scheduled Release Yes Yes Held Run Yes Yes Enable Yes Yes Disabled Disable Yes Yes Inactive or Failed 40 Monitor status values Table 2 identifies the possible status values for a monitor. In MIMIX Availability Manager, an icon can represent more than one status value. Hover over the icon to see the status value. Export Yes Import Yes a. This action is only valid when a monitor has an interface exit program that supports it. Table 1. Required status values for actions on monitors Action Available From Required Status Value (5250 emulator nomenclature) MIMIX Availability Manager 5250 emulator Table 2. Possible status values for monitors MIMIX Availability Manager 5250 emulator Description Action required FAILED/ACT The resulting actions of the monitor failed but the monitor remains active. If the monitor belongs to a group it will participate in the decision to trigger the group. FAILED The monitor has failed. The event program for the monitor requested that the monitor be ended and the status set to failed, an unexpected error occurred in the monitor, or the maximum number of restarts have been attempted. If the monitor belongs to a group, it will participate in the decision to trigger the group. Partially Active ENDING The monitor is ending normally. Once the monitor completes its shutdown activities, the status will be changed to either INACTIVE or FAILED depending on the return value from the last call to the event program. User action may be required if the state persists. In MIMIX Availability Manager, this icon may also be displayed when a monitor is starting. Ended INACTIVE The monitor has not been started. The monitor is not active. User action is necessary to start the monitor. Held HELD The monitor has been started, but its activity is suspended until a release is requested. Unknown The status of the monitor is unknown because collector services is not active. User action is necessary to start collector services. This status value is only possible in MIMIX Availability Manager. Disabled DISABLED The monitor has been disabled and is not active. If the monitor belongs to a group, it will not participate in the starting or triggering of the group. A disabled monitor is not affected by master monitor actions. User action is necessary to enable the monitor. Displaying a list of monitors on a system 41 (No icon) OK ACTIVE The monitor has been started and is active. SCHEDULED The monitor is scheduled. This value is only valid for time monitors. Table 2. Possible status values for monitors MIMIX Availability Manager 5250 emulator Description 42 Starting a monitor Only monitors with status values indicated in Table 1 can be started. If a group monitor is started, unless you specify otherwise, the request is extended to all monitors defined to the selected group monitor that have a status that allows them to be started. The status of a monitor may prevent it from participating in the start request. Monitors with a disabled status are never started with a group monitor. From MIMIX Availability Manager, do the following to start a monitor: 1. Select Monitors from the Details area in the navigation bar. 2. Locate the monitor you want in the list displayed on the Monitors window. Select the Start action and click . The Start Monitor window opens. 3. If the selected monitor is a journal or extended journal monitor, you will see fields for J ournal Receiver and Starting sequence number. Select the starting journal receiver and the first journal entry to be considered for monitoring. 4. If the selected monitor is a group monitor, select a value for the Scope of request. To start only the group monitor itself, select Name. 5. Click OK. From a 5250 emulator, do the following to start a monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 9 (Start) next to the monitor you want and press F4 (Prompt). 3. The Start Monitor (STRMON) display appears. If the monitor you are starting is a journal monitor or an extended journal monitor, you will see prompts for Journal Receiver and Starting large sequence number. Specify values that identify the starting journal receiver and the first journal entry to be considered for monitoring. 4. If the monitor you are starting is a group monitor, press F10 (Additional parameters). The Scope of request prompt appears. If you want to start only the group monitor itself, specify *NAME. 5. Press Enter. Ending a monitor 43 Ending a monitor Only monitors with status values indicated in Table 1 can be ended. If a group monitor is ended, unless you specify otherwise, the request is extended to all monitors defined to the selected group monitor that have a status that allows them to be ended. The status of a monitor may prevent it from participating in the end request. From MIMIX Availability Manager, do the following to end a monitor: 1. Select Monitors from the Details area in the navigation bar. 2. Locate the monitor you want in the list displayed on the Monitors window. Select the End action and click . The End Monitor window opens. 3. If the selected monitor is a group monitor, select a value for the Scope of request. To end only the group monitor itself, select Name. 4. Click OK. From a 5250 emulator, do the following to end a monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 10 (End) next to the monitor you want and press F4 (Prompt). 3. The End Monitor (ENDMON) display appears. 4. If the monitor you are ending is a group monitor, press F10 (Additional parameters). The Scope of request prompt appears. If you want to end only the group monitor itself, specify *NAME. 5. To process the request, press Enter. 44 Running condition and event programs for a monitor You can immediately run the condition and event programs associated with a monitor. The selected monitor name is passed to the Run Monitor (RUNMON) command. The programs are run under a separate job without performing any of the predefined condition checking that is standard for the event class of the monitor and without requiring an active status. The results of the run will be reflected in the monitor’s status. If the event program does not run successfully, the event failed flag and the shutdown flag are set to the same values as if the program failed when triggered by conditions specified for normal operation of the monitor. If the condition program is called, you will see messages in the message log indicating whether the condition was met. If the event program is called, you will see a message in the message log indicating the return code from the event program. The monitor detailed status is only updated if the event program is called. Ensure that the exit program, event program, and condition program you specify for a monitor are owned by a valid user profile. If you use a user profile that is not valid, the monitor job that is running the program will end abnormally. A user profile may be not valid if it is disabled or if *NONE is specified for its password. If you encounter this situation, change the ownership of the program or change the user profile. From MIMIX Availability Manager, do the following to immediately run the condition and event programs associated with a monitor: 1. Select Monitors from the Details area in the navigation bar. 2. Locate the monitor you want in the list displayed on the Monitors window. Select the Run action and click . 3. The Run Monitor window opens. Click OK. From a 5250 emulator, do the following to immediately run the condition and event programs associated with a monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 18 (Run) next to the monitor you want and press Enter. Enabling or disabling a monitor 45 Enabling or disabling a monitor The status of a monitor determines what actions you can perform. Table 1 identifies the status values required to enable or disable a monitor by invoking the Change Monitor Status (CHGMONSTS) command. For monitors defined to a group monitor, status determines whether the monitors participate in group decisions. The ability to change status is useful for preventing or ensuring participation by members of a group. A monitor is a member of a group when the value specified on its Monitor group parameter (MONGRP) matches the name of an existing group monitor (event class of *GROUP). Enabling a monitor Enabling a monitor changes its status from DISABLED to INACTIVE. Once enabled, a monitor can be started and run its normal operations, and other user actions can be taken as indicated in Table 1. Once enabled, a monitor can be started by the master monitor if it is configured to do so. If the monitor is defined to a group, it will participate in requests to start all monitors in the group and in decisions for the group monitor. From MIMIX Availability Manager, do the following to enable a monitor: 1. Select Monitors from the Details area in the navigation bar. 2. Locate the monitor you want in the list displayed on the Monitors window. Select the Enable action and click . 3. The Change Monitor Status window opens. Select Enabled for the Status value. 4. If the selected monitor is a group monitor, select a value for the Scope of request. To enable only the group monitor itself, select Name. 5. Click OK. From a 5250 emulator, do the following to enable a monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 20 (Enable) next to the monitor you want and press F4 (Prompt). 3. The Change Monitor Status (CHGMONSTS) display appears. The value *ENABLED should be preselected for the Status prompt. 4. If the selected monitor is a group monitor, press F10 (Additional parameters). The Scope of request prompt appears. If you want to enable only the group monitor itself, specify *NAME. 5. Press Enter. Disabling a monitor Table 1 identifies the status values required before a monitor can be disabled. 46 A monitor with a DISABLED status cannot run its normal operations and is prevented from starting with the master monitor if configured to do so. If it is defined to a group, it will not participate in requests to start all monitors in the group and will not participate in decisions for the group monitor. DISABLED monitors can be started individually. Once they are started, they will participate in the triggering decision for any group to which they belong. From MIMIX Availability Manager, do the following to disable a monitor: 1. Select Monitors from the Details area in the navigation bar. 2. Locate the monitor you want in the list displayed on the Monitors window. Select the Disable action and click . 3. The Change Monitor Status window opens. Select Disabled for the Status value. 4. If the selected monitor is a group monitor, select a value for the Scope of request. To enable only the group monitor itself, select Name. 5. Click OK. From a 5250 emulator, do the following to disable a monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 21 (Disable) next to the monitor you want and press F4 (Prompt). 3. The Change Monitor Status (CHGMONSTS) display appears. The value *DISABLED should be preselected for the Status prompt. 4. If the selected monitor is a group monitor, press F10 (Additional parameters). The Scope of request prompt appears. If you want to enable only the group monitor itself, specify *NAME. 5. Press Enter. Placing a monitor on hold 47 Placing a monitor on hold Placing a monitor on hold suspends all processing until a release request is received. Table 1 identifies the status values required before a monitor can be held. If a group monitor is held, unless you specify otherwise, the request is extended to all monitors defined to the selected group monitor that have a status that allows them to be held. The status of a monitor may prevent it from participating in the request. From MIMIX Availability Manager, do the following to hold a monitor: 1. Select Monitors from the Details area in the navigation bar. 2. Locate the monitor you want in the list displayed on the Monitors window. Select the Hold action and click . 3. The Hold Monitor window opens. If the selected monitor is a group monitor, select a value for the Scope of request. To hold only the group monitor itself, select Name. 4. Click OK. From a 5250 emulator, do the following to start a monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 13 (Hold) next to the monitor you want and press F4 (Prompt). 3. The Hold Monitor (HLDMON) display appears. If the monitor you selected is a group monitor, press F10 (Additional parameters). The Scope of request prompt appears. If you want to start only the group monitor itself, specify *NAME. 4. Press Enter. 48 Releasing a held monitor When you release a monitor that is being held (status of HELD), the monitor continues processing at the point where processing was suspended when it was placed on hold. If a held group monitor is released, unless you specify otherwise, the request is extended to all monitors defined to the selected group monitor that have a status of HELD. From MIMIX Availability Manager, do the following to release a held monitor: 1. Select Monitors from the Details area in the navigation bar. 2. Locate the monitor you want in the list displayed on the Monitors window. Select the Release action and click . 3. The Release Monitor window opens. If the selected monitor is a group monitor, select a value for the Scope of request. To release only the group monitor itself, select Name. 4. Click OK. From a 5250 emulator, do the following to release a held monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 14 (Release) next to the monitor you want and press F4 (Prompt). 3. The Release Monitor (RLSMON) display appears. If the monitor you are releasing is a group monitor, press F10 (Additional parameters). The Scope of request prompt appears. If you want to release only the group monitor itself, specify *NAME. 4. Press Enter. Working with the message log 49 Working with the message log The MIMIX message log provides a common location for you to see all messages related to MIMIX products. A consolidated list of messages for all systems in the installation library is available on the management system. Note: The target system only shows messages that occurred on the target system. LVI messages are informational messages and LVE messages are error or diagnostic messages. CPF messages are generated by an underlying operating function and may be passed up to the MIMIX product. Do the following to access the MIMIX message log: 1. Do one of the following to access the message log display: • From the MIMIX Basic Main Menu, select option 13 (Work with messages) and press Enter. • From the MIMIX Intermediate Main Menu, select option 3 (Work with messages) and press Enter. 2. The Work with Message Log appears with a list of the current messages. The initial view shows the message ID and text. 3. Press F11 to see additional views showing the message type, severity, the product and process from which it originated, whether it is associated with a group (for MIMIX, a data group), and the system on which it originated. 4. You can subset the messages shown on the display. A variety of subsetting options are available that allow you to manage the message log more efficiently. 5. To work with a message, type the number of the option you want and press Enter. The following options are available: • 4=Remove - Use this option if you want to delete a message. When you select this option, a confirmation display appears. Verify that you want to delete the messages shown and press Enter. The message is deleted only from the local system. • 5=Display message - Use this option to view the full text of the first level message and gain access to the second level text. • 6=Print - Use this option to print the information for the message. • 8=Display details - Use this option to display details for a message log entry including its from and to program information, job information, group information, product, process, originating system, and call stack information. • 9=Related messages - Use this option to display a list of messages that relate to the selected message. Related messages include a summary and any detail messages immediately preceding it. This can be helpful when you have a large message log list and you want to show the messages for a certain job. • 12=Display job - If job information exists on the system, you can use this option to access job information for a message log entry. The Work with J obs display appears from which you can select options for displaying specific information about the job. 50 Other operations available from a 5250 emulator The Work with Monitors display provides options for additional operations that are less frequently needed. The following procedures are only available from a 5250 emulator. Displaying monitor status details The Work with Monitors display shows the status of each monitor. Use this procedure to see more detailed information about a monitor, including the last time the event program was run, the conditions that triggered it, and whether the event program was run successfully. To display the status of a monitor, do the following: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 15 (Status) next to any monitor and press Enter. Note: If you select the UPS monitor, the UPS Monitor Status display will appear. Refer to “Displaying status for the UPS monitor” on page 141. 3. The Display Monitor Status display appears. The display includes the monitor name and information about the monitor including its event class, status, the outcome of the last time the event program was called, and the date and time of that call. Each type of monitor also includes additional information that is specific to its event class. If the monitor is a group monitor, you will see a summary of how many monitors defined to the group have the following current status values: active, inactive, failed, and failed/active. These are defined as follows: • Active monitors are monitors with a status of ACTIVE, HELD, SCHEDULED, STARTING, or ENDING. • Inactive monitors are monitors with an INACTIVE or DISABLED status. • Failed monitors are monitors with a status of FAILED. • Failed/active monitors are monitors with a status of FAILED/ACT. • If the last active monitor in the group becomes INACTIVE the group monitor will be ended. If the last active monitor in the group becomes FAILED or FAILED/ACT it will trigger the group monitor and cause the exit programs to run. Note: The group monitor status will stay ACTIVE until after the event program completes and then the status will be updated at that time. Other operations available from a 5250 emulator 51 Changing monitors You can change any of the parameters that define a monitor except for the name of the monitor. To change a monitor, do the following: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, verify that the status of the monitor you want is INACTIVE or DISABLED. 3. Type a 2 (Change) next to the monitor you want and press Enter. 4. The Change Monitor Object (CHGMONOBJ ) display appears. You can change the value shown for any prompt except for the name of the monitor. 5. Press Enter to display prompts that are associated with the specified event class. 6. You can change the value shown for any of the additional prompts. 7. When you are ready to accept the changes, press Enter. 8. If the value of the Interface exit program is *CMD, the Change Monitor Information (CHGMONINF) display appears. If necessary, change the command information and press Enter. Copying monitors To copy a monitor, do the following: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 3 (copy) next to the monitor you want and press Enter. 3. The Copy Monitor Object (CPYMONOBJ ) display appears. At the To monitor prompt, specify a name for the new monitor. The name you specify cannot already exist. Note: You cannot copy a group monitor. Deleting a monitor You cannot delete a group monitor that has an associated switch definition using this procedure. To delete a group monitor that is associated with a switch definition, refer to “Deleting a switch definition” on page 86. To delete a monitor, do the following: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, verify that the status of the monitor you want is INACTIVE or DISABLED. 3. Type a 4 (Delete) next to the monitor you want and press Enter. 52 4. The Confirm Delete of Monitors display appears. Verify that the name of the monitor shown is the monitor you want. Press Enter to delete the monitors or F12 (Cancel) to return to change your selection. Displaying a monitor To display a monitor, do the following: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 5 (Display) next to the monitor you want and press Enter. 3. The Display Monitor Object display appears. When you are ready to continue, press Enter. 4. If the value of the Interface exit program is *CMD, the Display Monitor Information (DSPMONINF) display appears. When you are ready to continue, press Enter. Printing a monitor To print a monitor, do the following: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 6 (Print) next to the monitor you want and press Enter. 3. A spooled file named MXMON is created that contains the monitor description. Use your local process to print your spooled files. Renaming a monitor Do the following to rename an existing monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, verify that the status of the monitor you want is INACTIVE or DISABLED. 3. Type a 7 (Rename) next to the monitor you want and press Enter. 4. The Rename Monitor Object (RNMMONOBJ ) display appears. At the To monitor prompt, specify a new name for monitor. The name you specify cannot already exist. 5. Press Enter to rename the existing monitor. Working with information for a monitor To work with user-specified information associated with a monitor, do the following: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. Other operations available from a 5250 emulator 53 2. From the Work with Monitors display, type a 12 (Work with) next to the monitor you want and press Enter. Note: This option is only valid for monitors that have an interface exit program specified. 3. The information you will see is dependent on what the interface exit program has been programmed to do when this option is selected. When this option is used, the interface exit program is only called as a pre-process call. Exporting and importing monitors MIMIX Monitor includes function that enables you to export and import monitors to another installation of MIMIX Monitor on the same system or on another system. This makes it easy for you to use the same monitor in another product library and to add additional packaged monitors. Notes: MIMIX does not support exporting or importing switch definitions or switch device entries. It is recommended that you export from a previous or same release and import from the same or a higher release. If you import a *GROUP monitor that represents a switch definition into a monitor installation, you will not be able to create a switch definition on the imported system for that group monitor. This is because the group monitor is created when the switch definition is created and cannot exist before the switch definition is created. If you want to create a switch definition of that name, you will have to delete the associated group monitor. The monitors that participate in the group would not be deleted. When you create the switch definition and the group monitor, you can add the switch device entries. Exporting a monitor When you export a monitor, you can export directly to another product library that contains MIMIX Monitor on the same system or to a holding file. The holding file can be sent to another system where it can be imported into a product library that contains MIMIX Monitor. To export a monitor, do the following: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 39 (Export) next to any monitor and press Enter. 3. The Export Monitor Object (EXPMONOBJ ) display appears. Do the following: Note: If you want to export multiple monitors type EXPMONOBJ on a command line and press Enter. Specify a generic name or the value *ALL at the Monitor prompt. 54 a. At the Monitor object file prompt, specify a file and library to which the monitor object will be exported. The default values *DFT and *CURLIB save the monitor object in file MM1050P in the current library. If you want to export the monitor object directly to another product library that contains MIMIX Monitor, specify MM1000P for the file name and specify the name of the library. If the file already exists, the file must have the same record format as MM1000P in MIMIX Monitor's product library. b. At the Monitor information file prompt, specify a file and library to which the command information associated with the monitor will be exported. Command information can be associated with any monitor that has *CMD specified for its interface exit program. The default values *DFT and *CURLIB save the command information in file MM2050P in the current library. If you do not want to export the command information associated with the monitor, specify *NONE. To export the command information directly to another product library that contains MIMIX Monitor, specify MM2000P for the file name and specify the name of the library. If the file already exists, the file must have the same record format as MM2000P in MIMIX Monitor's product library. c. At the Replace or add records prompt, specify what action to take if the monitor object and corresponding command information already exist in the files specified. The default value *REPLACE indicates that, if the objects or information exist, the existing monitor object and command information in the files will be replaced. The value *ADD indicates the monitor object and command information is added to the file only if they do not already exist. d. At the Create files prompt, specify whether or not the files specified should be created if they do not exist. 4. Press Enter to export the monitor. Importing a monitor The Import Monitor Object (IMPMONOBJ ) command enables you to import one or more monitor objects and their associated command information. Monitors can be imported directly from another MIMIX Monitor product library on the same system or from a holding file that contains the exported monitor. Use this command from the MIMIX Monitor product library on the system to which you are importing the monitors. Do the following to import a monitor: 1. From a command line within MIMIX Monitor, type IMPMONOBJ and press Enter. 2. The Import Monitor Object (IMPMONOBJ ) display appears. Do the following: a. At the From monitor definition prompt, specify the name of the monitor to be imported. Or, specify a generic name or *ALL to import multiple monitors. Other operations available from a 5250 emulator 55 b. At the Monitor prompt, specify the name of the monitor. The default value *NAME indicates that the name of the imported monitor is used. The name is added to the list of monitors for this installation of MIMIX Monitor. This parameter is ignored when a generic name or *ALL is specified for the From monitor definition prompt. c. At the From monitor object file prompt, specify the name of the file and the library from which the monitor object will be imported. The default values *DFT and *CURLIB import file MM1050P from the current library. The file you specify must have the same record format as file MM1000P in the MIMIX Monitor product library. To import a monitor object directly from another product library that contains MIMIX Monitor on this system, specify MM1000P and the name of the library from which to import the monitor object. d. At the Monitor information file prompt, specify the name of the file and library from which the associated command information will be imported. Command information can be associated with any monitor that has *CMD specified for its interface exit program. The default values *DFT and *CURLIB import file MM2050P from the current library. The file you specify must have the same record format as file MM2000P in the MIMIX Monitor product library. If you do not want to import the command information associated with the monitor, specify *NONE. To import the command information directly from another product library that contains MIMIX Monitor on this system, specify MM2000P for the file name and specify the name of the library. e. At the Replace or add records prompt, specify what action to take if the monitor object and corresponding command information already exist in the MIMIX Monitor product library. The default value *REPLACE indicates that, if the monitor objects or information exists, the existing monitor object and command information in the files will be replaced. The value *ADD indicates the monitor object and command information are added to the files only if they do not already exist. 3. Press Enter to import the monitor. Note: When a monitor is imported, MIMIX Monitor checks for the existence of the interface exit program. If the interface exit program exists, MIMIX Monitor calls the program. If the interface exit program does not exist, the import completes and a warning message is sent. Before any options on the Work with Monitors display can be used, the imported monitor must specify a valid value for the interface exit program. Either the interface exit program must exist or the imported monitor must be changed to call a valid interface exit program or to *NONE. Working with monitor job logs MIMIX Monitor automatically saves the job log of any monitor job that ends abnormally. A separate job log is used for each monitor that ends abnormally. Each of the following has a separate job log: master monitor, interval master monitor, each 56 synchronous journal monitor, interval monitor, message queue monitor, and time monitor. Also, each asynchronous job for journal monitors, interval monitors, message queue monitors, and group monitors have separate job logs. J ob logs are not automatically saved for monitors that end normally when end is requested by a user action or by a return code from the event program. If you want to save job logs, including asynchronous jobs, regardless of the ending status, you must change the job description for MIMIX Monitor. To see the list of job logs, type the command WRKSPLF MIMIXOWN and press Enter. To change the job description for MIMIX Monitor, do the following: 1. Type the command CHGJOBD JOBD(MIMIXQGPL/MIMIXMON) and press F4 (Prompt). 2. Specify the values for the message logging parameter as LOG(4 00 *SECLVL) and press Enter. Common parameters on the CRTMONOBJ command 57 CHAPTER 4 Creating user-defined monitors This section describes how to create monitor objects for user-defined monitors. Monitor objects can be created only from a 5250 emulator. “Common parameters on the CRTMONOBJ command” on page 57 identifies parameters that are common to multiple event classes of monitors. “Event classes” on page 71 identifies the predefined condition for each event class and the parameters that are used to identify the event, and provides detailed information about each event class. “Creating monitors” on page 61 provides procedures and tips for creating user- defined monitors. Common parameters on the CRTMONOBJ command The following information describes parameters on the Create Monitor Object (CRTMONOBJ ) command that apply to monitors of more than one event class. Unless noted, these parameters can be used to define a monitor of any event class. Monitor - The Monitor parameter specifies the name of the monitor definition. Each name in the list of monitors for an installation must be unique. Note: The name UPSMON, and monitor names that begin with the characters MM, are reserved names. Event class - The event class parameter specifies the event class type for the monitor. The event class identifies the type of event that triggers the monitor. For detailed information, see “Event classes” on page 71. Monitor group - The Monitor group parameter specifies a group to which the monitor belongs. The default value *DFT indicates that the monitor belongs to the default group of monitors. This parameter can be used in two ways when you specify a name: • To create a logical grouping of similar monitors so that you can subset the list of monitors that appears on the Work with Monitors display. For example, you may want to place all monitors that perform security checking activities into the same group. • To create a group of monitors that participate in the event triggering of a monitor of event class *GROUP (a group monitor). If the name you specify for the Monitor group parameter is in use as the name of an existing group monitor, or if a group monitor is created with the name you specify, the monitor automatically becomes part of the triggering criteria for the group monitor. Note: When you define a group monitor, the value of the Monitor group parameter must be either *DFT or the same name as the monitor. If *DFT is used, the value will be changed to the name of the monitor when the monitor definition record is created. Creating user-defined monitors 58 Interface exit program - The use of the Interface exit program parameter provides an optional way to perform additional programming associated with the monitor object. If you specify an interface exit program, then it is called both before and after an operation is performed on a monitor. If you want a monitor to run a particular command as the triggered event without having to write an exit program, specify *CMD for the Interface exit program and *NONE for the Event program. After the monitor is created you will be prompted for the command information on the Add Monitor Information display. The running of the command is performed when the event is triggered. Refer to the appropriate source for information about the required parameters of any command that you call in this way. Online help (F1 key) is available for operating system commands and MIMIX commands. Condition program - The Condition program parameter specifies the name and library of the user program that will be called when the predefined monitor conditions are met. The condition program can be used to check additional conditions before the event program is run. If a condition program is defined for the monitor object, it must specify a '0' in the return code in order for the condition to be met and the event program to be called. Event program - The Event program parameter specifies the name and library of the user program that is called when the predefined monitor conditions and user-defined conditions are met. An event program is used to handle the triggered event. Note: If no condition and event programs are defined, the triggered event does nothing. Job description - The Job description parameter specifies the name and library of the job description that is used when the monitor job is submitted or when asynchronous jobs are started for the monitor. Default values use the MIMIXOWN job description in library MIMIXQGPL. Retry attempts - The Retry attempts parameter specifies how many times the predefined condition and the user-defined conditions within a condition program must be met before the event program is called. This parameter allows the condition program the opportunity to recover from or recheck the condition that triggered the event. The Retry attempts parameter can be used for interval monitors, message queue monitors, and journal monitors that use synchronous processing. The parameter is ignored by time monitors and group monitors. When the value of the Retry attempts parameter is 0, the predefined condition is checked once and the condition program is called. If the user-defined conditions in the condition program are met, the event program is called. When you specify a value and a condition program, if the condition in the program is not met on a given call to the program, the retry attempts are reset. Both the predefined condition and the user-defined conditions in the condition program must be met the number of times specified before the event program is called. When no condition program is specified, only the predefined condition is checked the number of times specified before the event program is called. Common parameters on the CRTMONOBJ command 59 If you specify a value when no event program is specified, the parameter has no meaning and the monitor will run until it is manually ended. If you specify a Process type of asynchronous, you must specify 0 for the Retry attempts. Asynchronous processing does not allow the concept of retrying conditions. Exercise caution when using this parameter. It may not be appropriate to set the retry attempts to a value other than 0. For a message queue monitor the message IDs to be monitored must arrive on the queue and the conditions in the condition program must be met as many times as the retry value before the event program is called. This parameter is most appropriate for an interval monitor which specifies a subclass, where the process of an interval passing, a communications object being checked, and the condition program checking a user-defined condition is repeated multiple times before the event program is run. Process type - The Process type parameter specifies the way in which journal monitors and message queue monitors run the condition and event programs and how interval monitors operate. The default value is *SYNC. For journal monitors and message queue monitors that are processed synchronously, the condition and event programs are run synchronously in the monitor. When a received message ID or journal entry meets the monitoring criteria the condition and event programs are run within the monitor job. The next message ID or journal entry is not received until the condition and event programs complete. For interval monitors processed synchronously, the interval master monitor does not control the monitor. Instead, a separate job is started that waits for the specified time interval and optionally checks a communications object before it runs the condition and event programs. The interval wait time does not begin again until after the exit programs are completed. When you specify the value *ASYNC on a journal monitor or a message queue monitor, the condition and event programs are run asynchronously by starting a separate job to run them. When a received message ID or journal entry meets the monitoring criteria, the monitor starts a separate job to run the condition and event programs. The next message ID or journal entry is immediately received. Multiple jobs can be running condition and event programs simultaneously. When you specify the value *ASYNC on an interval monitor, the monitor is controlled by the interval master monitor. When the time interval is reached, the interval master monitor starts a separate job for the monitor to run the condition and event programs. The next time interval is immediately processed without waiting for the exit programs to complete. Multiple jobs can be running condition and event programs simultaneously. When you specify *ASYNC for an interval monitor, the monitor must have a minimum time interval of 5 minutes (300 seconds) to reduce the number of launched jobs. Start with master monitor - The Start with master monitor parameter specifies whether a monitor should be started when the master monitor is started. When you specify *YES, if the monitor’s status is INACTIVE or FAILED when the master monitor is started, the monitor will be started automatically. Monitors that have a DISABLED status are never started with the master monitor. Creating user-defined monitors 60 ASP group - The ASP group parameter specifies the name of the auxiliary storage pool (ASP) group that is associated with the monitor object. Valid only for journal monitors and message queue monitors, use this parameter to specify the name of the ASP group where the journal or message queue library exists. Description - Use the Description parameter to provide a description of the monitor that will appear in the Monitors window in MIMIX Availability Manager and the Work with Monitors display in a 5250 emulator. Creating monitors 61 Creating monitors All user-defined monitors consist of a monitor object and optional condition, event, and interface exit programs. Note: Although each type of program is optional, your monitor must have either a condition or an event program before the monitor can be started. If your monitor only uses an interface exit program, your program needs to control all operations of the monitor, including running the monitor. This information describes how to create a monitor for each of the event classes. “Programming for monitors” on page 144 describes the programming requirements for the condition, event, and interface exit programs. Creating a time monitor For information about time monitors, see “Time monitors (*TIME)” on page 76. Do the following to create a time monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 1 (Create) in the Opt column next to the blank line at the top of the list and press Enter. 3. The Create Monitor Object (CRTMONOBJ ) display appears. Do the following: a. At the Monitor prompt, provide a unique name for the monitor. b. At the Event class prompt, specify *TIME. c. If you want to assign this monitor to a grouping of similar monitors, either for participating in triggering a group monitor or for subsetting, specify a name for the Monitor group prompt. d. To call a program before (pre-exit) and after (post-exit) each operation performed on a monitor, specify the program name and library for the Interface exit program prompt. If you want to run a command when the event is triggered, refer to the tips for “Common parameters on the CRTMONOBJ command” on page 57. e. To call a program containing user-defined conditions after the predefined condition is met, specify the program name and library for the Condition program prompt. f. To call a program that initiates user-defined actions when the predefined conditions and user-defined conditions are met, specify the program name and library for the Event program prompt. Note: If you want to run a command instead of an event program, specify *NONE for the Event program prompt and specify *CMD for the Interface exit program prompt. After the monitor is created, you will be prompted to provide the command information. 62 g. To use a different job description to submit the monitor job and for asynchronous jobs started for the monitor, specify the name and library for the Job description prompt. h. Press Enter. Additional parameters will appear on the display. 4. Do the following to specify how often and when to run the time monitor. Refer to “Tips for time monitors” on page 62 if necessary. a. At the Frequency prompt, specify how often the condition and event programs are to be run. b. The Scheduled date and Scheduled day prompts are mutually exclusive. Specify a value for one of these prompts to indicate when the monitor is to run. Specify *NONE for the prompt you do not use. c. Specify the time of day that the monitor is to run at the Scheduled time prompt. 5. If you want time monitors in FAILED or INACTIVE state to automatically start when the master monitor is started, specify *YES for the Start with master monitor prompt. 6. Provide a text description of the monitor at the Description prompt and press Enter. 7. If you specified a frequency of *MONTHLY and a value for the Scheduled date prompt, the Relative day of month prompt appears. Press F1 (Help) to see a description of the possible values. Specify a value and press Enter. 8. If you specified *CMD for the Interface exit program, the Add Monitor Information (ADDMONINF) display appears. Do the following: a. Type the command that you want to use and provide the appropriate parameters and values. b. Type the name of the library in which the command resides in the Library parameter and press Enter. You can also type *DFT to use the library specified on the Command parameter. If no library is specified on the Command parameter, the library list is used to locate the command. If the command is found, the library name is retained. If you specify *LIBL, the library list is used to locate the command. Tips for time monitors Consider the following when you create a time monitor: • If your system or your job is configured to use J ulian date format, the monitor job is submitted to run as if the normal date format is in use. For example, you have a time monitor that specifies a Frequency of monthly (FRQ(*MONTHLY)) but the system uses the J ulian date format where days of the year are sequentially numbered rather than divided into months. The job for your time monitor is submitted to run as if the system uses a date format that divides the year into months. • If you specify a Frequency of monthly but a month does not contain the day specified on the Scheduled date parameter, the job is not run that month. For example, if SCDDATE(01/31/99) and FRQ(*MONTHLY) are specified, the job is Creating monitors 63 submitted on the 31st day of J anuary, March, May, J uly, August, October, and December. The job will not run in February, April, J une, September, and November. • To submit a job on the last day of every month, specify SCDDATE(*MONTHEND). • To submit a job that runs every day, specify SCDDAY(*ALL). • If a Scheduled time has not passed, a job will run on the specified date or day of the week according to any additional limits placed on the job by the parameters that control frequency and relative day of the month. For example: – You specify a scheduled date of *MONTHSTR and a scheduled time of 2 a.m. If today is the first day of the month and it is before 2 a.m., the job is submitted today. Otherwise, the job is submitted on the first day of the next month. – If SCDDAY(*FRI) and SCDTIME(12:00:00) are specified and you are adding this job schedule entry at 11:00 a.m. on a Friday, the job is submitted today. If you are adding the entry at 4:00 p.m. on a Friday or at 11:00 a.m. on a Monday, the job is submitted the following Friday. • The Relative day of month (RELDAYMON) parameter specifies the relative day of the month on which the monitor is run. The relative day of the month is valid only when a value is specified for the Scheduled day (SCDDAY) and the Frequency (FRQ) is specified as *MONTHLY. For example, if you specify FRQ(*MONTHLY) SCDDAY(*TUE) RELDAYMON(2), the job is submitted on the second Tuesday of every month. Creating a journal monitor For information about journal monitors, see “J ournal monitors (*J RN)” on page 74. Do the following to create a journal monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 1 (Create) in the Opt column next to the blank line at the top of the list and press Enter. 3. The Create Monitor Object (CRTMONOBJ ) display appears. Do the following: a. At the Monitor prompt, provide a unique name for the monitor. b. At the Event class prompt, specify *JRN. c. If you want to assign this monitor to a grouping of similar monitors, either for participating in triggering a group monitor or for subsetting, specify a name for the Monitor group prompt. d. To call a program before (pre-exit) and after (post-exit) each operation performed on a monitor, specify the program name and library for the Interface exit program prompt. If you want to run a command when the event is triggered, refer to the tips for “Common parameters on the CRTMONOBJ command” on page 57. 64 e. To call a program containing user-defined conditions after the predefined condition is met, specify the program name and library for the Condition program prompt. f. To call a program that initiates user-defined actions when the predefined conditions and user-defined conditions are met, specify the program name and library for the Event program prompt. Note: If you want to run a command instead of an event program, specify *NONE for the Event program prompt and specify *CMD for the Interface exit program prompt. After the monitor is created, you will be prompted to provide the command information. g. To use a different job description to submit the monitor job and for asynchronous jobs started for the monitor, specify the name and library for the Job description prompt. h. Press Enter, additional parameters will appear on the display. 4. If you want to retry the conditions a number of times before calling the event program, specify a value for the Retry attempts prompt. 5. At the Journal prompt, specify the name and library of the journal from which journal entries will be monitored. 6. At the Journal codes prompt, specify one or more journal codes to use to limit the journal entries to be monitored on the specified journal. 7. At the Journal entry types prompt, specify one or more journal entry types to use to limit the journal entries to be monitored on the specified journal. 8. If you want to use asynchronous processing so that the monitor starts a separate job to process the journal entry, specify *ASYNC for the Process type prompt. 9. If you want journal monitors in FAILED or INACTIVE state to automatically start when the master monitor is started, specify *YES for the Start with master monitor prompt. 10. If the journal to be monitored exists in an independent ASP, at the ASP group prompt specify the name of the primary ASP device within the ASP group. 11. The ASP group name is the name of the primary ASP device within the ASP group. 12. Provide a text description of the monitor at the Description prompt and press Enter. 13. If you specified *CMD for the Interface exit program, the Add Monitor Information (ADDMONINF) display appears. Do the following: a. Type the command that you want to use and provide the appropriate parameters and values. b. Type the name of the library in which the command resides in the Library parameter and press Enter. You can also type *DFT to use the library specified on the Command parameter. If no library is specified on the Command parameter, the library list is used to locate the command. If the command is Creating monitors 65 found, the library name is retained. If you specify *LIBL, the library list is used to locate the command. Creating a message queue monitor For information about message queue monitors, see “Message queue monitors (*MSGQ)” on page 75. Do the following to create a message queue monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 1 (Create) in the Opt column next to the blank line at the top of the list and press Enter. 3. The Create Monitor Object (CRTMONOBJ ) display appears. Do the following: a. At the Monitor prompt, provide a unique name for the monitor. b. At the Event class prompt, specify *MSGQ. c. If you want to assign this monitor to a grouping of similar monitors, either for participating in triggering a group monitor or for subsetting, specify a name for the Monitor group prompt. d. To call a program before (pre-exit) and after (post-exit) each operation performed on a monitor, specify the program name and library for the Interface exit program prompt. If you want to run a command when the event is triggered, refer to the tips for “Common parameters on the CRTMONOBJ command” on page 57. e. To call a program containing user-defined conditions after the predefined condition is met, specify the program name and library for the Condition program prompt. f. To call a program that initiates user-defined actions when the predefined conditions and user-defined conditions are met, specify the program name and library for the Event program prompt. Note: If you want to run a command instead of an event program, specify *NONE for the Event program prompt and specify *CMD for the Interface exit program prompt. After the monitor is created, you will be prompted to provide the command information. g. To use a different job description to submit the monitor job and for asynchronous jobs started for the monitor, specify the name and library for the Job description prompt. h. Press Enter, additional parameters will appear on the display. 4. If you want to retry the conditions a number of times before calling the event program, specify a value for the Retry attempts prompt. 5. At the Message queue prompt, specify the name and library of the message queue to be monitored. 6. At the Message identifier prompt, specify one or more message identifiers, 66 including generics, to monitor for on the specified message queue. 7. If you want to use asynchronous processing so that the monitor starts a separate job to process the message identifier, specify *ASYNC for the Process type prompt. 8. If you want message queue monitors in FAILED or INACTIVE state to automatically start when the master monitor is started, specify *YES for the Start with master monitor prompt. 9. If the message queue to be monitored exists in an independent ASP, at the ASP group prompt specify the name of the primary ASP device within the ASP group. 10. Provide a text description of the monitor at the Description prompt and press Enter. 11. If you specified *CMD for the Interface exit program, the Add Monitor Information (ADDMONINF) display appears. Do the following: a. Type the command that you want to use and provide the appropriate parameters and values. b. Type the name of the library in which the command resides in the Library parameter and press Enter. You can also type *DFT to use the library specified on the Command parameter. If no library is specified on the Command parameter, the library list is used to locate the command. If the command is found, the library name is retained. If you specify *LIBL, the library list is used to locate the command. Creating an interval monitor For information about interval monitors, see “Interval monitors (*INTERVAL)” on page 72. Do the following to create an interval monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 1 (Create) in the Opt column next to the blank line at the top of the list and press Enter. 3. The Create Monitor Object (CRTMONOBJ ) display appears. Do the following: a. At the Monitor prompt, provide a unique name for the monitor. b. At the Event class prompt, specify *INTERVAL. c. If you want to assign this monitor to a grouping of similar monitors, either for participating in triggering a group monitor or for subsetting, specify a name for the Monitor group prompt. d. To call a program before (pre-exit) and after (post-exit) each operation performed on a monitor, specify the program name and library for the Interface exit program prompt. If you want to run a command when the event is triggered, refer to the tips for “Common parameters on the CRTMONOBJ command” on page 57. Creating monitors 67 e. To call a program containing user-defined conditions after the predefined condition is met, specify the program name and library for the Condition program prompt. f. To call a program that initiates user-defined actions when the predefined conditions and user-defined conditions are met, specify the program name and library for the Event program prompt. Note: If you want to run a command instead of an event program, specify *NONE for the Event program prompt and specify *CMD for the Interface exit program prompt. After the monitor is created, you will be prompted to provide the command information. g. To use a different job description to submit the monitor job and for asynchronous jobs started for the monitor, specify the name and library for the Job description prompt. h. Press Enter, additional parameters will appear on the display. 4. If you want to retry the conditions a number of times before calling the event program, specify a value for the Retry attempts prompt. 5. At the Time interval (sec.) prompt, specify the length of time, in seconds, that MIMIX Monitor waits before optionally checking the communications object and, if the object is not active, starting the condition and event programs for the monitor again. The value specified must be equal to or greater than 300 if the Process type specified was *ASYNC. 6. Depending on what items you want the monitor to check you will need to select the following parameters: Table 3. Interval monitor parameter selections Desired action Interval subclass prompt choice If you do not need to have the monitor check additional parameters: 1. Specify *NONE for the Interval subclass prompt and press Enter 2. Proceed to Step 7. If you want to have the monitor check the status of a configuration object: 1. Specify *CFG for the Interval subclass prompt and press Enter. 2. At the Configuration object prompt, specify the name of the object to monitor. 3. At the Configuration type prompt, specify the type of the line, controller, or device to monitor and proceed to Step 7. If you want to check the status of a TCP/IP host address or alias: 1. Specify *TCP for the Interval subclass prompt and press Enter. 2. At the Host address or alias prompt, specify the TCP host address or alias to monitor. (Ensure that you place single quotes around the host address) and proceed to Step 7. 68 7. If you want to use asynchronous processing so that the interval master monitor controls the intervals and starts a separate job to run the condition and event programs, specify *ASYNC for the Process type prompt. 8. If you want interval monitors in FAILED or INACTIVE state to automatically start when the master monitor is started, specify *YES for the Start with master monitor prompt. 9. Provide a text description of the monitor at the Description prompt and press Enter. 10. If you specified *CMD for the Interface exit program, the Add Monitor Information (ADDMONINF) display appears. Do the following: a. Type the command that you want to use and provide the appropriate parameters and values. b. Type the name of the library in which the command resides in the Library parameter and press Enter. You can also type *DFT to use the library specified on the Command parameter. If no library is specified on the Command parameter, the library list is used to locate the command. If the command is found, the library name is retained. If you specify *LIBL, the library list is used to locate the command. Creating a group monitor For information about group monitors, see “Group monitors (*GROUP)” on page 77. If you are creating a group monitor for use in a switching scenario that requires a switch definition, ensure that you create the switch definition first. The switch definition automatically creates a group monitor of the same name. Note: If you are using MIMIX Model Switch Framework, the Create Switch Framework (CRTSWTFWK) command will automatically create a group If you want to check a communications link using the primary transfer definition specified in a system definition used in a replication environment: 1. Specify *SYSDFN for the Interval subclass prompt and press Enter. 2. At the System definition prompt, specify a system definition that is defined to MIMIX. Press F4 (Prompt) to see a list of system definitions and then proceed to Step 7. If you want to check a communications link using a transfer definition used in a replication environment: 1. Specify *TFRDFN for the Interval subclass prompt and press Enter. 2. At the Transfer definition prompt, specify the three-part name of the transfer definition that is defined to MIMIX and which defines the communications method to be monitored. All three parts of the transfer definition must be specified. Press F4 (Prompt) to see a list of transfer definitions and then proceed to Step 7. Table 3. Interval monitor parameter selections Desired action Interval subclass prompt choice Creating monitors 69 monitor. For more information refer to the CRTSWTFWK command description in “MIMIX Model Switch Framework commands” on page 105. Do the following to create a group monitor: 1. From the MIMIX Basic Main Menu, select option 12 (Work with monitors) and press Enter. 2. From the Work with Monitors display, type a 1 (Create) in the Opt column next to the blank line at the top of the list and press Enter. 3. The Create Monitor Object (CRTMONOBJ ) display appears. Do the following: a. At the Monitor prompt, provide a unique name for the monitor. b. At the Event class prompt, specify *GROUP. c. Specify *DFT at the Monitor group prompt. d. To call a program before (pre-exit) and after (post-exit) each operation performed on a monitor, specify the program name and library for the Interface exit program prompt. If you want to run a command when the event is triggered, refer to the tips for “Common parameters on the CRTMONOBJ command” on page 57. e. To call a program containing user-defined conditions after the predefined condition is met, specify the program name and library for the Condition program prompt. f. To call a program that initiates user-defined actions when the predefined conditions and user-defined conditions are met, specify the program name and library for the Event program prompt. Note: If you want to run a command instead of an event program, specify *NONE for the Event program prompt and specify *CMD for the Interface exit program prompt. After the monitor is created, you will be prompted to provide the command information. g. To use a different job description to submit the monitor job and for asynchronous jobs started for the monitor, specify the name and library for the Job description prompt. h. Press Enter. 4. If you want group monitors in FAILED or INACTIVE state to automatically start when the master monitor is started, specify *YES for the Start with master monitor prompt. 5. Provide a text description of the monitor at the Description prompt and press Enter. 6. If you specified *CMD for the Interface exit program, the Add Monitor Information (ADDMONINF) display appears. Do the following: a. Type the command that you want to use and provide the appropriate parameters and values. b. Type the name of the library in which the command resides in the Library parameter and press Enter. You can also type *DFT to use the library specified 70 on the Command parameter. If no library is specified on the Command parameter, the library list is used to locate the command. If the command is found, the library name is retained. If you specify *LIBL, the library list is used to locate the command. Event classes 71 Event classes MIMIX Monitor supports monitor objects based on the following event classes: *INTERVAL, *J RN, *EXDJ RN, *MSGQ, *TIME, *GROUP, and *PREDFN. In user defined monitors, you can use any event class except *PREDFN or *EXDJ RN to define the activity that calls programs associated with the monitor. Predefined conditions for event classes and their associated parameters The predefined conditions for each event class are: *INTERVAL - The specified time interval has passed, and optional subclass checking has been performed. *TIME - The specified date and time has occurred. *MSGQ - A specified message ID has arrived in the monitored message queue. *J RN - A specified journal transaction has arrived in the monitored journal. *GROUP - The predefined condition for a group monitor is that all monitors in the group, with the exception of DISABLED and INACTIVE monitors, have changed to a FAILED or FAILED/ACT status. When the last active monitor in the group (other than the group monitor itself) changes to a status of INACTIVE, FAILED, or FAILED/ACT the group monitor assesses whether to run the condition and event programs specified for the group monitor. Table 4 identifies which parameters on the CRTMONOBJ command are used to define the event for each event class. The *GROUP event class is not shown because it does not require parameters to define the event. Table 4. Parameters on CRTMONOBJ command that define the predefined condition for the specified event class Parameters Event Classes *INTERVAL *TIME *MSGQ *JRN Time interval (sec.) X Interval subclass X Configuration object X Configuration type X Host address or alias X System definition X Transfer definition X Frequency X Scheduled date X Scheduled day X 72 Interval monitors (*INTERVAL) Interval monitors use an interval (in seconds) to determine how often to run condition and event programs. Interval monitors are different from time monitors because interval monitors are based on a number of seconds passing, not on time of day. Subclasses - Interval monitors support the concept of subclasses to check that the communications link or object being monitored is active. When a subclass is specified on an interval monitor, additional predefined conditions are checked after the time specified in the interval has passed. You can specify retry attempts so that the monitor will retry the communications link or object, attempt recovery where possible, and call the condition program multiple times before the event program is called. The following subclasses are supported: • Configuration object - for the configuration object subclass (*CFG), the status of a line, controller, or device object is checked after the time specified in the interval is past. If the object is not active, the monitor attempts recovery if the value of retry attempts parameter is other than zero. If the object can be recovered on a retry attempt, the condition and event programs are not called and the monitor continues to monitor the object. If the object cannot be recovered on a retry attempt, the condition program is called. If the object is not recovered after the specified number of retry attempts, the event program is called. • TCP/IP interface - for the TCP/IP subclass (*TCP), the status of a host address or alias is checked after the time specified in the interval is past. If there is no response, the condition and event programs are triggered. When a value other than zero is specified for the retry attempts parameter, the monitor will check the status of the host address or alias and call the condition program multiple times before the event program is called. No recovery is attempted. • System definition - a system definition contains a transfer definition, so when you specify a system definition, the communication link defined by the transfer definition is verified. The subclass of system definition (*SYSDFN) interacts with system definitions and transfer definitions used in MIMIX replication Scheduled time X Relative day of month X Message queue X Message identifier X J ournal X J ournal codes X J ournal entry types X Table 4. Parameters on CRTMONOBJ command that define the predefined condition for the specified event class Parameters Event Classes *INTERVAL *TIME *MSGQ *JRN Event classes 73 configurations. For information on configuring a system definition, refer to the MIMIX Administrator Reference book. • Transfer definition - a transfer definition defines a communications link that can be used to determine if the two systems that define the link are able to communicate. The subclasses of transfer definition (*TFRDFN) interact with transfer definitions used in MIMIX replication configurations. For information on configuring a transfer definition, refer to the MIMIX Administrator Reference book. For *SYSDFN and *TFRDFN subclasses of an interval monitor, the communications link is verified when the time interval has passed. If the communications link is not responding, the condition and event programs are run. When a value other than zero is specified for the retry attempts parameter, the monitor will check the communications link and call the condition program multiple times before the event program is called. No recovery is attempted on the communications link. Process type - Interval monitors also support the concept of asynchronous and synchronous processing. You choose what is used by the value you specify for the Process type (PRCTYPE) parameter. The interval master monitor controls all asynchronous interval monitors. Asynchronous interval monitors are monitors that, each time an interval passes, use a separate process to run the condition and event programs. The interval for an asynchronous interval monitor begins when the interval master monitor is started, or if the interval master monitor is already active, when the interval master monitor handles the start request. For example, a monitor with a 300 second interval defined will cause the interval master monitor to start a separate process to run the condition and event programs after 300 seconds and every 300 seconds thereafter. (300 seconds is the smallest valid value for an asynchronous interval.) Several processes can be simultaneously running for the same monitor if the interval time is reached before the first separate process has completed running the condition and event programs. The running of the event program is dependent on the success of the condition program. The Retry attempts parameter is not allowed when asynchronous processing is used. Synchronous interval monitors run as a separate process where the condition and event programs are called in-line after the interval has passed. The next time interval does not begin until the condition and event programs have completed. With synchronous interval monitors, the concept of retry attempts requires that the predefined conditions, the passing of the time interval, the sub-class checking, and user-defined conditions (the condition program) must be met multiple times before the event program is called. When to use an interval monitor You can use an interval monitor when you want to: • Check for a condition at regularly timed intervals that can be expressed in seconds or if you need to check communications objects or links. Interval monitors are activated after the specified time interval has passed. Interval monitors should be used when the conditions being monitored should be checked on a regular basis and not at a specific time. For example, you may have a monitor that checks to see when the DASD threshold exceeds a certain percentage. You may want to create an event 74 program that clears certain output queues or runs a command to reclaim spool storage. To determine if the threshold value is exceeded, you could set this monitor to run at regular intervals. • Monitor communications links and objects. If you specify a line, controller, or device to monitor, you can have the monitor attempt recovery on a failed object. You can also use interval monitors in your network to monitor communications links to determine if a system in the network has failed. • Watch communications lines for failures and have an event program that attempts to reestablish communications. Journal monitors (*JRN) You can use journal monitors to define journal, journal codes, and journal entry types to monitor. There is a separate monitor job for each monitor object definition of this event class. You determine which entries the journal monitor receives from a journal receiver by specifying journal codes and journal entry types. The journal monitor starts at a specified entry in the currently attached journal receiver. The journal monitor receives and processes only the entries that meet your filtering criteria of specified journal codes and journal entry types. When the monitor receives an entry, the condition program runs. The condition program determines if the event program will run. J ournal monitors have a process type parameter that determines whether entries that meet the selection criteria are processed synchronously or asynchronously. In synchronous processing, the monitor calls the condition and event programs and the next journal transaction is not received until the event program completes. In asynchronous processing, a separate job is started to process the message, call the condition and event programs, and update the status of the monitor upon completion. Asynchronous processing allows the monitor to immediately process the next entry without waiting for processing of the previous entry to complete. A synchronous journal monitor can also specify a retry attempt value. When a retry value is specified, multiple journal entries must meet the monitoring criteria and the condition program will be called each time before the event program is called. A journal monitor writes an entry to the journal being monitored when the following situation occurs. If you specify the parameter FROMENT2(*LASTPROC) when you start a journal monitor, the monitor starts checking entries at the last sequence number processed. If no additional entries were written to the journal since the monitor processed the last entry, the monitor writes entry U ‘MX’ to the journal. Note: The parameter Starting sequence number (FROMENT) can be used when the journal supports *MAXOPT2 for the receiver size and when sequence number values do not exceed 10 digits. However, FROMENT2 is recommended. When to use a journal monitor You can use journal monitors when you need to watch a journal for certain journal codes and entry types as they occur. You can monitor a journal for any activity that is important in your operating environment. Event classes 75 For example, you may want to define a monitor to watch a journal for F-EJ entries for a member within a file. These types of entries may indicate a problem such as journaling ended for file XYZ. Files indicated by these entries may no longer have adequate backup and recovery protection. Your event program could alert an operator or build a list of files, which is used by a program that attempts to resolve the problem. In another example, you may want a monitor to watch for J -PR entries that indicate the start of a new journal receiver or for other journal codes associated with changing receivers. As journal receivers change you could have an event program that saves the journal receiver to tape. You might want an event program that checks if there are an unusually high number of receivers associated with the journal because that could indicate problems with your journal maintenance process. Or, you may want to create a security monitor that reads the Security Audit J ournal and watches for authority failure entries and notifies an operator when these entries occur. Extended journal monitors (*EXDJRN) Extended journal monitors (*EXDJ RN) are journal monitors shipped with MIMIX that perform a specific purpose in a MIMIX environment. You cannot change these monitors. This event class is not an available choice when you create a monitor. Message queue monitors (*MSGQ) You can use message queue monitors (*MSGQ) to define a message queue and a list of message identifiers (including generic values) for which to monitor. There is a separate monitor job for each monitor object definition of this event class. When a message arrives on the message queue, it is compared to the list of monitored message IDs. If the monitor receives a message ID that appears in the list then the condition program runs. If the conditions are met, the event program runs. Message IDs that arrive on the queue before the message queue monitor is started are ignored. Only messages that arrive on the message queue while the monitor is active are processed. Message queue monitors have a process type parameter that determines whether message IDs that meet the selection criteria are processed synchronously or asynchronously. In synchronous processing, condition and event programs are called by the message queue monitor and must complete before the next message on the queue is received. In asynchronous processing, a separate job is started to process the message, call the condition and event programs, and update the status of the monitor upon completion. Asynchronous processing allows the monitor to immediately process the next message in the queue without waiting for processing of the previous message to complete. A synchronous message queue monitor can also specify a retry attempt value. When a retry value is specified, multiple messages must arrive that meet the monitoring criteria and the condition program will be called each time before the event program is called. You should ensure that no other processes, including another message queue monitor, receive messages from the monitored message queue. Also, you should not use the Clear Message Queue (CLRMSGQ) command while a monitor is processing 76 messages from a message queue. Message queue monitors use the message key to identify the last message that was processed from the monitored queue and thereby determine the next message to receive. When certain commands are used on a message whose key is being processed by the message queue monitor, the message key can become not valid. These commands are the CLRMSGQ command and the Receive Message (RCVMSG) command when RMV(*YES) is specified. If a new message arrives in the queue that fits into the same space as the removed message, the new message may be assigned the same key. If this situation occurs before MIMIX Monitor resets the key that is not valid, the message queue monitor may omit unprocessed messages and resume processing at the wrong location. However, if the monitor determines that the key has become not valid the primary and secondary message queues and the message log are notified. The message queue monitor will receive the last message on the queue, as it does when the monitor is first started, and resume receiving messages from that point. For more information see “Working with the message log” on page 49. When to use a message queue monitor You should use a message queue monitor when you need to watch a message queue for the occurrence of certain message IDs. Message queue monitors are appropriate for situations where a process or an application sends messages to a specific message queue. For example, you may want to monitor the primary message queue used by MIMIX for messages indicating that a file has been placed on hold and notify the system operator when this occurs. Or, you may want to monitor the system operator message queue for messages indicating user profiles that have been disabled because the number of invalid sign-on attempts has been exceeded. You could have an event program send a break message to the operator, or automatically reset the user profiles, or run an additional security program. Additionally you could have a monitor watch for certain messages in the system operator message queue and automatically recycle controllers. Time monitors (*TIME) Time monitors (*TIME) use the IBM i job scheduler to determine when to run condition and event programs. You can set the monitor object definition to run a job once or at regular intervals, based on the date and time of day. The master monitor controls all monitor object definitions for time monitors. The master monitor adds a job schedule entry for each time monitor and periodically verifies that the job is properly scheduled. The job name is the same as the monitor name. If the monitor object definition is ended the job schedule entry is removed. When the scheduled date and time occur, the condition program runs. If the conditions are met, the event program runs. For more information see “Master monitor” on page 21. When to use a time monitor You should use a time monitor when you need to check for a condition or take an action based on a date or a day and time. Time monitors allow you to specify a time and a frequency in which to run the monitor (once, weekly, or monthly) and then Event classes 77 specify a scheduled date or day of the week. The scheduled date and day parameters are mutually exclusive. You can optionally schedule the relative day of the month (for example, the last day of a month or the second Tuesday of each month). For example, you may want to define a monitor to run a usage report on the last day of each week or to print backup logs from a nightly backup. Group monitors (*GROUP) When you create a group monitor, you will also need to create multiple monitors to participate in a group decision. The association between the group monitor and the participating monitors is formed when the name of the group monitor (which has an event class of *GROUP) is specified as the value of the Monitor group (MONGRP) parameter in the participating monitors. The participating monitors trigger when the group monitor’s condition and event programs are run. When the group monitor is started, all participating monitors with a status of INACTIVE or FAILED are started. Monitors with a DISABLED status are not started when the group monitor is started and do not participate in decisions for the group monitor (DISABLED status is considered inactive). However, DISABLED monitors can still be started individually. Once started, their status changes and the monitors will then participate in the triggering decision for the group. If the group monitor is active, it checks the status of all participating monitors whenever the status of a participating active monitor changes. The group monitor remains active and does not consider running its programs until after the last of its participating active monitors either ends or fails. For more information see “Group monitor processing” on page 25. When to use a group monitor You can use group monitors when you want multiple monitors to participate in a decision or when you want to coordinate activity among multiple monitors. One use of a group monitor is in a switching scenario. You can define several monitors to watch communications links or objects on your production system. At any moment, if all participating communications monitors (a sub-class of an interval monitor) agree that the system is not active, the group monitor is triggered. The event program for the group monitor can be programmed to use the built-in switching capabilities of MIMIX to switch users to a backup system and switch the direction of replication. A sample event program MSFEVENT is shipped with this product and is in file MMTEMPLSRC in the product library. Predefined monitors (*PREDFN) Predefined monitors (*PREDFN) are a special event class that identifies monitors that are shipped with the MIMIX Monitor product and do not fit into any other event class. Predefined monitors cannot be created or changed by users. Predefined monitors may include: • Additional interfaces for specific functions 78 • Specialized commands that allow for a limited degree of customizing • Enabling for exit programs that include user-defined programming This event class is not an available choice when you create a monitor. 79 CHAPTER 5 Working with switch definitions This section provides procedures for creating and working with switch definitions. Switch definitions require the use of system definitions and transfer definitions configured in the same MIMIX installation. Refer to “Preparing for a switch” on page 31 for additional information about using switch definitions. You may also want to consider using the MIMIX Model Switch Framework in your switching environment. See “Using the MIMIX Model Switch Framework” on page 100. 80 Accessing the Work with Switch Definitions display The Work with Switch Definitions display enables you to work with all of your switch definitions from one interface. You can also access displays to work with devices defined to a switch definition and the monitors associated with a switch definition. To access the Work with Switch Definitions display, do one of the following: • From the MIMIX Basic Main Menu, select option 11 (Configuration menu) and press Enter. Then, from the MIMIX Configuration Menu, select option 10 (Work with switches) and press Enter. • Using the name of the library in which MIMIX Monitor is installed for library-name, type library-name/WRKSWT and press Enter. Creating switch definitions 81 Creating switch definitions When you create a switch definition, a group monitor (event class *GROUP) is automatically created with the same name and specifying the same event program as the switch definition. Switch definitions use system definitions and transfer definitions to define the systems to be switched and the communications protocol used between the systems. The system definitions and transfer definitions must be configured in the MIMIX installation library before they as specified in a switch definition. You can create switch definitions using three different types of switching control. The following subtopics are customized for each type of switching control. Note: The MIMIX Model Switch Framework does not need a switch definition. If you are using the Create Switch Framework (CRTSWTFWK) command in the MIMIX Model Switch Framework, you can specify SWTDFN(*NONE) on this command. However, without a switch definition and monitors to trigger the switch, automated unplanned switching will not take place. Creating a switch definition for TCP Do the following to create a switch definition that uses IP impersonation: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 1 (Create) in the Opt column next to the blank line at the top of the list and press Enter. 3. The Create Switch Definition (CRTSWTDFN) display appears. Do the following: a. Specify a unique name for the definition at the Switch prompt. Once the switch definition is created, its name cannot be changed. b. At the Switch type prompt, specify *TCP. c. At the Production system definition prompt, specify the name of a system definition defined to MIMIX that is the production system during normal operations. To see a list of system definitions available in this product library, press F4 (Prompt). d. At the Backup system definition prompt, specify the name of a system definition defined to MIMIX that is the backup system during normal operations. The default value *LOCAL uses the system definition for this system. To see a list of system definitions available in this product library, press F4 (Prompt). e. At the Transfer definition prompt, specify the name of the transfer definition that defines the communication method between the production system and the backup system. You should specify the controlling system if it is not the backup system. To see a list of system definitions available in this product library, press F4 (Prompt). f. At the Event program prompt, specify the name and library of the user program that is called by the group monitor when the predefined monitor conditions and 82 user-defined conditions are met. An event program is used to handle the triggered event. Note: If you want to specify a condition program, you must change the group monitor that is automatically created when the switch definition is created. 4. Press Enter. Additional parameters appear on the display. 5. At the Impersonation alias or address prompt, specify the name of a host alias or an address to be used for IP impersonation. 6. At the Logon message prompt, you can accept the default message or provide the text that you want to appear on devices defined to the switch when the Start Switch Screen (STRSWTSCN) command is used during a switching operation. 7. At the Description prompt, provide a text description of the switch definition and press Enter. Creating a switch definition for hardware switching Do the following to create a switch definition that uses switching hardware from Black Box Corporation: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 1 (Create) in the Opt column next to the blank line at the top of the list and press Enter. 3. The Create Switch Definition (CRTSWTDFN) display appears. Do the following: a. Specify a unique name for the definition at the Switch prompt. Once the switch definition is created, its name cannot be changed. b. At the Switch type prompt, specify *SM900A. c. At the Production system definition prompt, specify the name of a system definition defined to MIMIX that is the production system during normal operations. To see a list of system definitions available in this product library, press F4 (Prompt). d. At the Backup system definition prompt, specify the name of a system definition defined to MIMIX that is the backup system during normal operations. The default value *LOCAL uses the system definition for this system. To see a list of system definitions available in this product library, press F4 (Prompt). e. At the Transfer definition prompt, if the system controlling the switch operations is not the backup system, specify the name of a transfer definition that defines the communication between the production system and the backup system. f. At the Event program prompt, specify the name and library of the user program that is called by the group monitor when the predefined monitor conditions and user-defined conditions are met. An event program is used to handle the triggered event. Note: If you want to specify a condition program, you must change the group Creating switch definitions 83 monitor that is automatically created when the switch definition is created. 4. Press Enter. Additional parameters appear on the display. 5. At the Production system switch code prompt, verify that the value shown represents the hardware switch setting necessary to have devices attached to the production system. If necessary, change the value. 6. At the Gang switch control device prompt, specify the name of the communication object to the switching hardware. (This was created with the CRTDEVASC command.) 7. At the Device remote location name prompt, specify the remote location name to use for communications to the switching hardware. (This is the used for the CRTDEVASC command). 8. At the Security character prompt, specify the value that matches the dip switch settings in the remote system gang controller. The security character is required for all communications with the switching hardware. 9. At the Dial sequence prompt, verify that the default value *LOCAL matches your switching hardware configuration. If you are using a remote configuration, specify *AUTODIAL or a dial sequence. 10. At the Logon message prompt, you can accept the default message or provide the text that you want to appear on devices defined to the switch when the Start Switch Screen (STRSWTSCN) command is used during a switching operation. 11. At the Description prompt, provide a text description of the switch definition and press Enter. Creating a switch definition for type *NONE Use this procedure if you want to program the IP impersonation or hardware switching yourself. When you use this procedure, the switch definition you create will not include the information MIMIX Monitor requires to perform a hardware switch or perform IP impersonation. If you want to use those functions with a switch definition created in this way, your event program must include all of the necessary programming. If the Set Switch Source (SETSWTSRC) command is used on a switch definition created with this procedure, no switching occurs. The event program associated with the switch definition can be run without starting the associated group monitor. One reason why you might want to create a switch definition in this way is to associate device entries with a switch definition so that you can send a message to the devices using the Start Switch Screen (STRSWTSCN) command. Do the following to create a switch definition where MIMIX Monitor does not perform switching: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 1 (Create) in the Opt column next to the blank line at the top of the list and press Enter. 84 3. The Create Switch Definition (CRTSWTDFN) display appears. Do the following: a. Specify a unique name for the definition at the Switch prompt. Once the switch definition is created, its name cannot be changed. b. At the Switch type prompt, specify *NONE. c. Verify that the value of the Production system definition prompt is what you want. The default value *NONE indicates that MMIX Monitor will not verify the status of the production system. d. At the Backup system definition prompt, specify the name of a system definition defined to MIMIX that is the backup system during normal operations. The default value *LOCAL uses the system definition for this system. To see a list of system definitions available in this product library, press F4 (Prompt). e. At the Transfer definition prompt, if the system controlling the switch operations is not the backup system, specify the name of a transfer definition that defines the communication between the production system and the backup system. f. At the Event program prompt, specify the name and library of the user program that is called by the group monitor when the predefined monitor conditions and user-defined conditions are met. An event program is used to handle the triggered event. Note: If you want to specify a condition program, you must change the group monitor that is automatically created when the switch definition is created. 4. Press Enter. Additional parameters appear on the display. 5. At the Logon message prompt, you can accept the default message or provide the text that you want to appear on devices defined to the switch when the Start Switch Screen (STRSWTSCN) command is used during a switching operation. 6. At the Description prompt, provide a text description of the switch definition and press Enter. Changing a switch definition 85 Changing a switch definition To change a switch definition, do the following: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 2 (Change) next to the switch definition you want and press Enter. 3. The Change Switch Definition (CHGSWTDFN) display appears. Press Enter to see all parameters for this switch type. 4. Make the changes you need. If you change the value of the Switch type, press Enter to see the additional parameters associated with the new type. Note: You cannot change the name of an existing switch definition. 5. To accept the changes, press Enter. 86 Deleting a switch definition This procedure will delete the group monitor associated with the switch definition. To delete a switch definition, do the following: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, verify that the value of the Status column for the switch definition you want to delete is not ACTIVE. 3. Type a 4 (Delete) next to the switch definition you want and press Enter. 4. The Confirm Delete of Switches display appears. Verify that the switch definition on the display is the one you want to delete and press Enter. Displaying a switch definition 87 Displaying a switch definition To display a switch definition, do the following: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 5 (Display) next to the switch definition you want and press Enter. 3. The Display Switch Definition display appears showing the values for the specified switch definition. 88 Printing a switch definition To print a switch definition, do the following: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 6 (Print) next to the switch definition you want and press Enter. 3. A spooled file is created that contains the switch definition. Use your local process to print your spooled files. Working with monitors for a switch definition 89 Working with monitors for a switch definition You can access the monitors associated with a switch definition from either of the following displays: • Work with Monitors display - All monitors associated with a switch definition are listed on this display along with other monitors. If you know the name of the group monitor associated with the switch definition, you can start or end the monitor from this display. For more information, see “Displaying a list of monitors on a system” on page 39. • Work with Switch Definitions display - Option 12 (Work with monitors) from this display will access the Work with Monitors display, subsetted to show only the group monitor associated with the selected switch definition and any other monitors that participate in the group decision. For more information, see “Accessing the Work with Switch Definitions display” on page 80. Starting monitors for a switch definition This procedure starts the group monitor for the switch definition and extends the request to any other monitors that participate in the group decision that have a status that allows them to be started. The status of a monitor may prevent it from participating in the start request. Additionally, the group monitor must have a condition or event program associated with it or it will not start. For information about what monitor status values are required for a start request, see Table 1 in topic “Actions available for monitors” on page 39. Note: If you know the name of the group monitor associated with a switch definition, you can start it from the Work with Monitors display. Any monitors in the same group which have a status that permits them to be started with the group monitor will also be started. See “Starting a monitor” on page 42 Do the following to start the monitors for a switch definition: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 1. From the Work with Switch Definitions display, type a 9 (Start) next to the switch definition you want and press Enter. 2. For the switch definition you selected, you should see the value in the Status column change from INACTIVE to ACTIVE. Ending monitors for a switch definition This procedure ends the group monitor for the switch definition and extends the request to any other monitors that participate in the group decision that have a status that allows them to be ended. The status of a monitor may prevent it from participating in the request. For information about what monitor status values are required for an end request, see Table 1 in topic “Actions available for monitors” on page 39. Note: If you know the name of the group monitor associated with a switch definition, you can end it from the Work with Monitors display. Any monitors in the same 90 group which have a status that permits them to be end with the group monitor will also be ended. See “Ending a monitor” on page 43. Do the following to end the monitors for a switch definition: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 10 (End) next to the switch definition you want and press Enter. 3. For the switch definition you selected, you should see the value in the Status column change from ACTIVE to ENDING, FAILED, or INACTIVE. Switching users manually 91 Switching users manually The Set Switch Source (SETSWTSRC), is only one of the commands that you should include in your event program to automate a switching operation. The SETSWTSRC command switches users from the production to the backup system or from the backup system to the production system. Refer to “What to include in your programs” on page 146 for more information about what to include in an event program to automate a switching operation. This set of steps will not result in the event program for the switch definition being run. To start a switching operation, do the following: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 11 (Set source) next to the switch definition you want and press Enter. 3. The Set Switch Source (SETSWTSRC) display appears. For the Data source prompt, specify the value for the system to which you are switching. 4. Press F10 (Additional parameters). 5. If switch definition is of type *TCP and you want MIMIX Monitor to end or start the interface as needed on the production system, specify *YES for the Alter production interface prompt. Note: The AUTOSTART option on the TCP/IP interface is only altered if MIMIX has ended the TCP/IP interface. If you use the default value *NO, you must take action to manually end or start the interface to the production system. If the interface is active on the production system and you specify *NO on a switch to the backup system, you must end the TCP interface manually before you continue with Step 7 so that you do not have two interfaces started which use the same impersonation address or alias. 6. If the switch definition is of type *SM517A and you want MIMIX Monitor to force the switching hardware to change settings, specify *YES for the Force hardware switch prompt. Refer to “Synchronizing settings in the switching hardware” on page 92 for more information about when you should force a change. 7. To perform the switch, press Enter. One of the following occurs: • For a switch definition of type *TCP, the impersonation address or alias defined to the switch is started or ended on the appropriate systems. • For a switch definition of type *SM517A or SM900A the physical switch is performed. MIMIX Monitor uses the HDWSWT parameter specified in the switch definition and the value you specified for the Data source (DTASRC parameter) to determine the appropriate setting. For example, if the switch definition includes HDWSWT(*A) and you specified to switch to the backup system, the setting changes to B and all resources connected are redirected to the backup system. 92 • For a switch definition of type *NONE, you will see the Work with Switch Definitions display. No activity is taken for the switch definition. 8. If you specified *NO for the Alter production interface prompt and you are switching to the production system, you must start the interface on the production system. Refer to “Configuring an automated switch” on page 106 for information on how to use MIMIX Model Switch Framework to automatically switch systems. Synchronizing settings in the switching hardware If the switch definition is of type *SM517A, you may find that the “A” or “B” indicator on the gang switch controller does not correspond to the switch settings on the rack chassis. Either of the following situations can cause this condition: • You are running in production mode and someone manually changes the switch setting on the rack chassis. (You may want to lock the setting and remove the key to prevent this from happening again.) • You performed a manual switch to the backup system and now want to perform an automated switch back to the production system. You can use the MIMIX Monitor command SETSWTSRC or the procedure “Switching users manually” on page 91 to synchronize the hardware settings. When you specify *YES for the Force hardware switch prompt, MIMIX Monitor checks the hardware settings and will force a change at the hardware level if the settings do not match what is expected for the requested switch operation. In these examples, it is assumed that the switch definition specifies HDWSWT(*A) and that you use hardware setting A for production. Table 5. Hardware switch settings Physical Settings Result of SETSWTSRC (FORCE*YES) Rack Chassis Remote Sys- tem Gang Controller Switch To Rack Chassis Remote Sys- tem Gang Controller Effect on Users A B Backup B B Devices and users are switched Production A A No effect. Rack chassis is not changed, users and devices are not switched. Switching users manually 93 B A Backup B B No effect. Rack chassis is not changed, users and devices are not switched. Production A A Devices and users are switched Table 5. Hardware switch settings Physical Settings Result of SETSWTSRC (FORCE*YES) Rack Chassis Remote Sys- tem Gang Controller Switch To Rack Chassis Remote Sys- tem Gang Controller Effect on Users 94 Displaying status for a switch definition To display the status of a switch definition do the following: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type a 15 (Status) next to the switch definition you want and press Enter. 3. The Display Switch Status display appears. This display is automatically updated as changes to the status occur. Figure 7. Displaying switch status The example in Figure 7 shows how the following information is displayed. • The left-most box contains information about the production system. • The right-most box contains information about the backup system. • The center-top box indicates where users are attached. • The center-bottom box indicates the status of the group monitor associated with the switch definition. • The color blue indicates that the system or monitor is active. • The color red indicates that the system or monitor is inactive. • Arrows between the system boxes and the group monitor box indicate the direction of data flow. Di spl ay Swi t ch St at us SYSTEMB Swi t ch def i ni t i on: MYTCP3 Syst em Syst em Name : SYSTEMA Name : SYSTEMB User s ar e on St at us: I NACTI VE SYSTEMA St at us: ACTI VE Type: PRODUCTI ON Type: BACKUP Moni t or I NACTI VE Swi t ch Set t i ng: A Swi t ch Set t i ng: B St ar t ed Cur r ent Legend . Dat e 3/ 19/ 99 3/ 19/ 99 Ti me 11: 27: 39 11: 27: 46 Act i ve I nact i ve F3=Exi t F12=Cancel The Switch Setting indicator only appears when the switch type is *SM900A or *SMS517A Running the event program for a switch definition 95 Running the event program for a switch definition To run the event program for a switch definition, do the following: 1. Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. 2. From the Work with Switch Definitions display, type 18 (Run user program) next to the switch definition you want and press Enter. 3. The event program runs immediately without starting the group monitor. 96 Accessing the Work with Device Entries display By defining devices to the switch definition and using the Start Switch Screen (STRSWTSCN) command during a switching operation, you can notify users of the status of the system. The Work with Device Entries display shows a list of the devices that are defined to the system and enables you to work with the devices. Note: The use of switch device entries is optional. However, if you define devices you should also define a logon message in the switch definition. If you define device entries to a switch definition, the devices will be allocated and will receive a special logon screen when the STRSWTSCN command is used for that switch definition. To access the Work with Device Entries display for a selected switch definition, do one of the following: • Use the procedure in “Accessing the Work with Switch Definitions display” on page 80 to access the Work with Switch Definitions display. Then, type a 13 (Work with devices) next to the switch definition you want and press Enter. • Using the name of the switch definition you want for name, type the command WRKSWTDEVE SWITCH(name) and press Enter. Adding all devices to a switch definition If you want to add entries to the switch definition for all devices on the system, do the following: 1. From the Work with Switch Definitions display, type a 13 (Work with devices) next to the switch definition you want and press Enter. 2. The Work with Device Entries display appears. Press F8 (Load device entry). 3. The Load Switch Device Entries (LODSWTDEVE) display appears. Verify that you want to load all devices. If necessary, change the value for the Device prompt. 4. At the Replace or add records prompt, specify the value that indicates action you want MIMIX Monitor to take if a device already exists in the list for the switch definition and press Enter. Adding a device entry To add a device entry to the switch definition, do the following: 1. From the Work with Device Entries display, type a 1 (Add) next to the blank line at the top of the list and press Enter. 2. The Add Switch Device Entry (ADDSWTDEVE) display appears. Provide the name of the device and a text description of the device and press Enter. Changing a device entry To change a device entry that is defined to the switch definition, do the following: 1. From the Work with Device Entries display, type a 2 (Change) next to the entry Accessing the Work with Device Entries display 97 you want and press Enter. 2. The Change Switch Device Entry (CHGSWTDEVE) display appears. Change the text description of the device and press Enter. Removing a device entry To remove a device entry that is defined to the switch definition, do the following: 1. From the Work with Device Entries display, type a 4 (Remove) next to the entry you want and press Enter. 2. The Remove Switch Device Entry (RMVSWTDEVE) display appears. Verify the device is the one you want to remove and press Enter. Displaying a device entry To display a device entry that is defined to the switch definition, do the following: 1. From the Work with Device Entries display, type a 5 (Display) next to the entry you want and press Enter. 2. The Display Switch Device Entry (DSPSWTDEVE) display appears showing the devices name and description. Printing a device entry To print a spooled file that contains a description of a device entry that is defined to the switch definition, do the following: 1. From the Work with Device Entries display, type a 6 (Print) next to the entry you want and press Enter. 2. The spooled file is created that contains the switch definition. Use your local process to print your spooled files. 98 Displaying and ending the switch screen Each switch definition can have its own logon message defined. During a switching operation, you can display a message to devices defined to the switch definition by using the Start Switch Screen (STRSWTSCN) command. When the STRSWTSCN command is run, the devices are allocated and the logon screen message is displayed on the devices. A companion command, End Switch Screen (ENDSWTSCN) should be used when the switching operation is complete to release the devices, allowing users to sign on. Note: To automate switching operations, you should include the STRSWTSCN and ENDSWTSCN commands in your event program. Displaying the switch screen To allocate the devices and send the logon message, do the following: 1. Type the command STRSWTSCN and press F4 (Prompt) 2. Specify the name of the switch definition you want and press Enter. Ending the switch screen To release the devices allocated by the switch definition, do the following: 1. Type the command ENDSWTSCN and press F4 (Prompt) 2. Specify the name of the switch definition you want and press Enter. Changing the logon message during a switch If you want to change the message displayed during the switching operation, use the Change Switch Definition (CHGSWTDFN) command to change the text of the logon message. If you want inform users at various points during the switch process, use the CHGSWTDFN command multiple times. Table 6 shows an example of what you might include in your event program to inform users of the status of a switching operation. This example shows a partial event Displaying and ending the switch screen 99 program that controls switching the direction of replication in MIMIX. In this example, the switch definition name is CRITDATA. Refer to the MIMIX Operations book for information about switching the direction of a data group. Table 6. Example of automation code for switching messages / * St ar t t he l ogon scr een, acqui r e t he devi ces */ STRSWTSCN SWI TCH( CRI TDATA) / * Change t he message t o not i f y user t hat t he swi t ch t o t he backup */ / * syst emi s bei ng st ar t ed. */ CHGSWTDFN SWI TCH( CRI TDATA) MSG( ' St ar t i ng swi t ch' ) / * Change t he message t o not i f y user t hat MI MI X Repl i cat or pr oduct */ / * i s swi t chi ng dat a gr oup di r ect i on. */ CHGSWTDFN SWI TCH( CRI TDATA) MSG( ' Swi t chi ng dat a gr oups f or MI MI X Repl i cat or ' ) / * Change t he message t o not i f y user t hat t he swi t ch i s compl et e */ CHGSWTDFN SWI TCH( CRI TDATA) MSG( ' Swi t chi ng compl et e' ) / * End t he l ogon scr een, r el ease t he devi ce. */ ENDSWTSCN SWI TCH( CRI TDATA) Using the MIMIX Model Switch Framework 100 CHAPTER 6 Using the MIMIX Model Switch Framework This chapter provides conceptual and reference information about MIMIX Model Switch Framework. What is MIMIX Model Switch Framework? The MIMIX Model Switch Framework is a set of programs and commands that provide a consistent framework for performing planned or unplanned switches. The commands are packaged with MIMIX Enterprise and MIMIX Professional. Typically, a Certified MIMIX Consultant assists you in setting up the programs and the switching environment. MIMIX Model Switch Framework provides the underlying support for the MIMIX Switch Assistant ™ interface within MIMIX Availability Manager and for the 5250 emulator switching interface accessible from option 5 on the MIMIX Basic Main Menu. These preferred user interfaces are ready to use after a default switch framework is configured and is identified to MIMIX in the Default model switch framework (DFTMSF) policy for the installation. Note: For information about using MIMIX Switch Assistant or using option 5 on the MIMIX Basic Main Menu, see online help or the MIMIX Operations book. The MIMIX Operations book also describes how to set policies for switching, including policies that help you keep within best practices for switching regularly. Although not preferred, you can also use the MIMIX Model Switch Framework in these ways: • Manually by running the RUNMON command on the associated group monitor, or using Option 18, Run User Program on the Work with Switch Definitions display. • Manually by running the Run Switch Framework (RUNSWTFWK) command. • Automatically (triggered by associated monitors). Phases of switching in MIMIX Model Switch Framework 101 Phases of switching in MIMIX Model Switch Framework Each phase of a switch as shown by the steps in Figure 8 is needed to ensure a complete (planned or unplanned) switch. The phases are described below. Step 1: Switchover - This phase moves production system users to the backup system. You will need two switchover processes, one for a planned switch and one for an unplanned switch. For detailed information about the events in this phase, see “Events and status: Starting a planned switch to a backup system” on page 109 and “Events and status: Starting an unplanned switch to a backup system” on page 110. Step 2: Synchronization - This phase replicates changes made on the backup system, while the backup system acted as the temporary production system. In a basic MIMIX environment, you would perform this phase after the production system is up and running again. For detailed information about the events in this phase, see “Events and status: Starting the switch synchronization” on page 111. Step 3: Switchback - This phase switches users to the production system after all changes have been replicated to the production system by the synchronization process. For detailed information about the events in this phase, see “Events and status: Returning to the production system” on page 112. In Figure 8, the term backup system refers to the original backup system where the MIMIX Model Switch Framework programs are stored. The term production system 102 refers to the Production system definition (PRDSYSDFN) parameter from the CRTSWTFWK and CHGSWTFWK commands. Figure 8. MIMIX switch cycle Operating requirements 103 Operating requirements The MIMIX Model Switch Framework requires the following: • MIMIX Enterprise or MIMIX Professional version 7 must be installed, including the current service pack. • The user profile used to run the MIMIX Model Switch Framework commands and which own its programs must be a valid user profile. A user profile may be not valid if it is disabled or if *NONE is specified for its password. If you encounter this situation, change the ownership of the program or change the user profile. Also, the user profile must have MIMIX product level authority equivalent to *OPR. • In order to use the preferred user interfaces described in the MIMIX Operations book, the default switch framework must be defined and specified in the installation policies. 104 Securing your MIMIX Model Switch Framework environ- ment To secure your MIMIX Model Switch Framework environment, you should: • Set the product-level security to ON for all products in the installation library. • Ensure that the user profiles that run MIMIX Model Switch Framework commands have the same level of authority to the commands in each of the following products: MIMIX DB2 Replicator, MIMIX Object Replicator, and MIMIX Monitor. Refer to the Using License Manager book for information on setting product-level security and change authority levels for user profiles. The commands used in these procedures support the value *ALL for the product as an easy way to consistently set product-level security and authorization levels in multiple products. MIMIX Model Switch Framework commands 105 MIMIX Model Switch Framework commands The following commands are supplied with the MIMIX Model Switch Framework. • Create Switch Framework (CRTSWTFWK) - This command creates the switch framework control area which controls switching scenarios between two systems. The initial status of the control area is set to PCMP which indicates that a switch to the backup system can be performed. You can run more than one switch framework process at a time. For example, you could have two production systems switch to the same backup system. To run multiple switch processes enter the CRTSWTFWK command and specify a unique library for each system for the Exit program library parameter. When you issue the Create Switch Framework (CRTSWTFWK) command it also creates a data area and a group monitor. The data area and group monitor will have the same name as the switch framework. For more information about group monitors refer to “Group monitors (*GROUP)” on page 77 and “Changing monitors” on page 51. • Change Switch Framework (CHGSWTFWK) - This command changes the switch framework control area which controls switching scenarios between two systems. • Check Switch Framework (CHKSWTFWK) - This command checks the switch framework control information and reports the status of the switching operation. When you enter this command the system issues a message describing the current state of the switch operation. For more information see “MIMIX Model Switch Framework status codes” on page 117. • Delete Switch Framework (DLTSWTFWK) - This command deletes the switch framework control area. • Retrieve Switch Framework (RTVSWTFWK) - This command is used in a CL program to retrieve the current status of the switch framework. This command returns the same status indicators as the CHKSWTFWK command. For more information see “MIMIX Model Switch Framework status codes” on page 117. • Run Switch Framework (RUNSWTFWK) - This command designates the system that you want to use as the source system and the switch operation that you want performed. You should run this command once for each of the phases of a switch. This command can only be run from the system where the MIMIX Model Switch Framework exists. By design, this is the original backup system. 106 Configuring an automated switch To set up an automated switch environment using MIMIX Model Switch Framework, perform the following: 1. Run the Create Switch Framework (CRTSWTFWK) command to create the MIMIX Model Switch Framework definition for your switching environment. 2. Edit the MIMIX Model Switch Framework user exit programs to make them specific for the systems involved with the switch. These programs are described in “MIMIX Model Switch Framework user exit programs” on page 121. 3. Edit the MSFEVENT event program to ensure it is applicable to your switching environment. This program is shipped with the MIMIX Model Switch Framework and is located in file MMTEMPLSRC in the MIMIX installation library. 4. Run the Create Switch Definition (CRTSWTDFN) command to create a MIMIX Monitor switch definition and specify EVTPGM(MSFEVENT). Enter option 12 on the Work with Switch Definitions (WRKSWT) display, next to the switch definition you just created to work with the monitor definitions associated with it. 5. Create the monitors that will control your switching environment. Refer to the subclass information in “Interval monitors (*INTERVAL)” on page 72. 6. Return to the Work with Switch Definitions (WRKSWT) display and start the switch definition. This will also start the monitors that control your MIMIX Model Switch Framework definition. 7. To enable the switch framework to be used with MIMIX Switch Assistant or with the switching option on the MIMIX Basic Main Menu, the framework created in Step 1 must be specified as the value of the Default model switch framework (DFTMSF) policy for the installation. For detailed information about setting policies, see the MIMIX Operations book. About the RUNSWTFWK command 107 About the RUNSWTFWK command The Run Switch Framework (RUNSWTFWK) command is used to perform the switchover, synchronization, and switch back processes. RUNSWTFWK provides underlying support for MIMIX Switch Assistant. When you are using the MIMIX Model Switch Framework to perform a switching operation, the MIMIX Model Switch Framework will issue status messages to inform you of the current status of the switching operation. During a switching operation, MIMIX Model Switch Framework waits for the data group to end before continuing processing. As long as the submit of the switch is successful, MIMIX Model Switch Framework processes the next data group in line. It does not wait for the switch to complete. Thus, a failure during a switching operation may result in a partially switched status. In the event that MIMIX Model Switch Framework fails during a switching operation, you must resolve the problem that occurred on the data group as well as complete the switch of the data group manually. For information about switching, see the MIMIX Operations book. The RUNSWTFWK command can only be run from the backup system. When you enter the RUNSWTFWK command you can specify: • If you want the MIMIX Model Switch Framework to automatically start the data groups after a planned switch or if you would rather start the data groups yourself. • If you want MIMIX to set the auditing level when performing a STRDG operation. You also have the option to manually ensure that the audit levels for all objects that are configured for replication by MIMIX have been set properly, otherwise, replication errors may occur. • The Wait time (seconds) (WAIT) prompt is used to specify the number of seconds to wait for all of the active data group processes to end. The function of the default value *DFT is different for planned switches than it is for unplanned switches. For a planned switch, the value *DFT is equivalent to the value *DGSELECT. For an unplanned switch, the value *DFT is set to wait 300 seconds (5 minutes) for all of the active data group processes to end. • If you specify a value for the WAIT parameter you can use the Timeout option parameter (TIMOUTOPT) to specify what action to take when the wait time you specified is reached. The function of the default value *DFT is different for planned switches than it is for unplanned switches. For a planned switch, the value *DFT is equivalent to the value *QUIT. When the value specified for the WAIT parameter is reached, the current process quits and returns control to the caller. For an unplanned switch, the value *DFT is equivalent to the value *NOTIFY. When the value specified for the WAIT prompt is reached, an inquiry message is sent to notify the operator of a possible error condition. • Whether or not you want the MIMIX Model Switch Framework to switch a data group when there are data group entries with an active (pending) status. The Conditions that end switch (ENDSWT) parameter is used to specify which conditions should end the switch process. The function of the default value *DFT is different for planned switches than it is for unplanned switches. 108 – For a planned switch, the value *DFT is equivalent to the value *ALL. The value *ALL uses all available options to end the switch process and is the most conservative way to switch data groups. Additionally, choosing ENDSWT(*ALL) ensures that your programs will automatically include any future ENDSWT parameter values that may be added to maintain a conservative approach to the switching operation. – For an unplanned switch, the value *DFT – is equivalent to the value *NONE. The value *NONE does not end switching even when conditions exist that are not compatible with best practices for switching. For example, if open commit cycles exist at the time of a switch, the uncommitted changes are not applied to the target system, and the data may be lost if the open commits are not resolved before the data group is started following the switch. – For an unplanned switch, the switch process is ended if there are any backlogs for the database apply process (similar to the value *DBPND). No other conditions that end switching are checked and switching is not ended even when conditions exist that are not compatible with best practices for switching. For example, if open commit cycles exist at the time of a switch, the uncommitted changes are not applied to the target system and the data may be lost if the open commits are not resolved before the data group is started following the switch. – For more information about how to check for pending object activity entries and open database commit cycles, see the MIMIX Operations book. • Whether or not you want the MIMIX Model Switch Framework to create and attach a new journal receiver for the user (database) journal during the switching operation. If you do not want the MIMIX Model Switch Framework to create new journal receivers for a specified data group choose CHGUSRRCV(*NO). • Whether or not you want the MIMIX Model Switch Framework to create and attach a new journal receiver for the system (audit) journal (QAUDJ RN) during the switching operation. If you want the MIMIX Model Switch Framework to create a new journal receiver for the first data group that handles object replication you should choose CHGSYSRCV(*FIRST). For more information about the options available to you when you are using the RUNSWTFWK command, enter the command and press F1 when the cursor is at the top of the display. RUNSWTFWK success and failure indicators The following sections identify the events that occur during each phase of a a switch and their resulting status indicators or messages for success or failure. You can also find a descriptive summary of each phase in online help for MIMIX Switch Assistant or online help for the switching option on the MIMIX Basic Main Menu. Status values are displayed in the content area of the MIMIX Switch Assistant window and in the job log. RUNSWTFWK success and failure indicators 109 Events and status: RUNSWTFWK command is invoked The following is the initialization process flow that occurs when you issue the RUNSWTFWK command: Events and status: Starting a planned switch to a backup system When you start a planned switch from the production system to the backup system, MIMIX does the following: • Ends the user production and backup environments on the appropriate systems. • Switches the selected data groups. • Starts the user production environment on the local (backup) system. • Optionally, starts the backup environment on the remote system and starts the selected data groups. Table 8 shows the process flow that occurs when the RUNSWTFWK PRC(*BCKUP) TYPE(*PLANNED) command is invoked: Table 7. RUNSWTFWK initialization process RUNSWTFWK events Success status/MSG Fail status/MSG Check Switch status for enabled status LVE8001 Get list of data group definitions, if there are no data groups to process, send LVE8002. LVE8002 If *PROD or *BCKUP is specified: • Determine if there are potential errors. • Call SWTFWKCFM confirmation program. If *SYNC, call switch confirmation program SWTFWKCFM. If SWTFWKCFM returns a ‘1’ to end processing then send message LVE8005 LVE8005 Table 8. RUNSWTFWK planned backup RUNSWTFWK PRC(*BCKUP) TYPE(PLANNED) events Success status or messages Fail status or mes- sages Check the switch status to determine if the system is in the correct state to run. BESD LVE8004 If associated with a switch definition, end the switch. BBEB Call the ENDBCKUP user program to end backup on the backup system. LVE8006 BEBF Check the local data area for a successful indicator. BBEP LVE8007 BEBF 110 Events and status: Starting an unplanned switch to a backup system When you start an unplanned switch from the production system to the backup system, MIMIX does the following: • Ends the user backup environment on the local system. • Switches the selected data groups. • Starts the user production environment on the local system. Call the ENDPROD user program to end production on the production system LVE8006 BEPF Check the local data area for a successful indicator. BDGD LVE8007 BEPF End selected data groups. BSWT LVE8007 BEDG Switch selected data groups. BSSS LVE8003 BESW If associated with a switch definition, then run the SETSWTSRC command. BBSP BSSF LVE8009 Call the STRPROD user program to start production on the backup system. LVE8006 BSPF Check the local data area for a successful indicator. BCMP LVE8007 BSPF Optional, if you want to start the data groups. BBSB Call the STRBCKUP user program to start the backup on the original production system. BSTR LVE8006 BSBF Check the local data area for a successful indicator. LVE8007 BSBF Call the DGSELECT user program to determine which data groups to start. LVE8003 BEST Run STRDG command for selected data groups. ACMP Table 8. RUNSWTFWK planned backup RUNSWTFWK PRC(*BCKUP) TYPE(PLANNED) events Success status or messages Fail status or mes- sages RUNSWTFWK success and failure indicators 111 Table 9 shows the process flow that occurs when the RUNSWTFWK PRC(*BCKUP) TYPE(*UNPLANNED) command is invoked: Events and status: Starting the switch synchronization When you start the synchronization step of the switch operation, MIMIX starts the selected data groups with the original backup system as the source system. Also, the user backup environment is started on the remote system Table 10 shows the process flow that occurs when the RUNSWTFWK PRC(*SYNC) command is invoked: Table 9. RUNSWTFWK unplanned backup RUNSWTFWK PRC(*BCKUP) TYPE(UNPLANNED) Events Success Status or Messages Fail Status or Mes- sages Check the switch status to determine if the system is in the correct state to run. FBEB LVE8004 Call the ENDBCKUP user program to end backup on the backup system. LVE8006 FEBF Check the local data area for a successful indicator. FDGD LVE8007 FEBF End selected data groups. FSWT LVE8007 FEDG Switch selected data groups. FSSS LVE8003 FESW If associated with a switch definition, then run the SETSWTSRC command. FBSP LVE8009 FSSF Call the STRPROD user program to start production on the backup system. LVE8006 FSPF Check the local data area for a successful indicator. FCMP LVE8007 FSPF Table 10. RUNSWTFWK synchronization RUNSWTFWK PRC(*SYNC) Events Success Status or Messages Fail Status or Mes- sages Check the switch status to determine if the system is in the correct state to run. SBSB LVE8004 Call the STRBCKUP user program to start backup on the production system. LVE8006 SSBF 112 Events and status: Returning to the production system When you start the switch back to the production system from the backup system, MIMIX does the following: • Ends the user production and backup environments on the appropriate systems. • Switches and starts the selected data groups. • Starts the production environment on the remote system. • Optionally, starts the backup environment and data groups on the appropriate systems. Note: Before you perform this step, you should ensure that the data group entries are synchronized. If the original switch was unplanned, you should perform journal analysis to find any orphaned entries and take appropriate actions to correct any errors. Table 11 shows the process flow that occurs when the RUNSWTFWK PRC(*PROD) command is invoked: Check the local data area for a successful indicator, if successful set the status code. SSTR LVE8007 SSBF Call the DGSELECT user program to determine which data groups to start, if end immediate is selected. LVE8003 SEST Run STRDG command for selected data groups. SCMP Table 10. RUNSWTFWK synchronization RUNSWTFWK PRC(*SYNC) Events Success Status or Messages Fail Status or Mes- sages Table 11. RUNSWTFWK PRC(*PROD) RUNSWTFWK PRC(*PROD) Events Success Status or Messages Fail Status or Mes- sages Check the switch status to determine if the system is in the correct state to run. PBEB LVE8004 Call the ENDBCKUP user program to end backup on the production system. LVE8006 PEBF Check the local data area for a successful indicator. PBEP LVE8007 PEBF Call the ENDPROD user program to end production on the backup system. LVE8006 PEPF Check the local data area for a successful indicator. PDGD LVE8007 PEPF RUNSWTFWK success and failure indicators 113 End selected data groups. PSWT LVE8007 PEDG Call SWTDG on the selected data groups or switch the selected data groups. PSSS LVE8003 PESW If there is an associated switch definition, then run the SETSWTSRC command PBSP LVE8009 PSSF Call the STRPROD user program to start production on the production system. LVE8006 PSPF Check the local data area for a successful indicator. PSPC LVE8007 PSPF Optional if you want to start the data groups PBSB Call the STRBCKUP user program to start backup on the backup system. LVE8006 PSBF Check the local data area for a successful indicator. PSTR LVE8007 PSBF Call the DGSELECT user program to determine which data groups to start. LVE8003 PEST Call STRDG on selected data groups. PSSD If associated with a switch definition, then start the switch. PCMP Table 11. RUNSWTFWK PRC(*PROD) RUNSWTFWK PRC(*PROD) Events Success Status or Messages Fail Status or Mes- sages 114 Enabling the MIMIX Model Switch Framework To enable the MIMIX Model Switch Framework you would specify: CHGSWTFWK SWTFWK( switch-framework-control-area) STATUS( *ENABLED) Disabling the MIMIX Model Switch Framework You can disable the MIMIX Model Switch Framework by entering the following command: CHGSWTFWK SWTFWK( switch-framework-control-area) STATUS( *DI SABLED) MIMIX Model Switch Framework messages 115 MIMIX Model Switch Framework messages The messages issued by the MIMIX Model Switch Framework are sent to the interactive job log of the user running the command and to the MIMIX message log. You can use the WRKMSGLOG command to view the MIMIX message log entries. 116 Completing a switch after encountering errors If you encounter an error condition during one of the switch phases you can complete the switch phase without restarting the entire process.To restart the switch operation from the last status checkpoint, enter the RUNSWTFWK command with the same parameters that were used with the command when it was initially entered. Depending on the type of failure that you encounter you may need to perform additional steps before issuing the RUNSWTFWK command. Note: MIMIX Switch Assistant provides information to resolve the error and where to restart the process. MIMIX Model Switch Framework status codes 117 MIMIX Model Switch Framework status codes The following status codes may be returned when you issue a CHKSWTFWK or RTVSWTFWK command. Table 12. MIMIX Model Switch Framework status codes Status codes Description These status codes are associated with switching back to the original production system PBEB Switch back to the original production system before the ENDBCKUP program is run on the remote system PBEP Switch back to the original production system before the ENDPROD program is run on the local system PBSB Switch back to the original production system before the STRBCKUP program is run on the local system PBSP Switch back to the original production system before the STRPROD program is run on the remote system PCMP Switch back to the original production system is complete (planned or unplanned switch to backup is next step) PDGD Switch back to the original production system, ending data groups (ENDDG) from the backup system to the production system. PEBF Switch back to the original production system, an error was detected or reported by the user when running the ENDBCKUP program on the remote system PEDG Switch back to the original production system, an error was detected in ENDDG or the user requested an immediate end from the DG selection program. PEPF Switch back to the original production system, an error was detected or reported by the user when running the ENDPROD program on the local system PEST Switch back to the original production system, an error was detected in STRDG or the user requested an end from the DG selection program PESW Switch back to the original production system, an error was detected in SWTDG or the user requested an end from the DG selection program PSBF Switch back to the original production system, an error was detected or reported by the user when running STRBCKUP on the local system PSPC Switch back to the original production system, STRDG was *NO, no data groups were started. PSPF Switch back to the original production system, an error was detected or reported by the user when running STRPROD on the remote system 118 PSSD Switch back to the original production system, starting the associated switch definition (STRSWT), if one exists. PSTR Switch back to the original production system before the STRDG processing is done PSWT Switch back to the original production system before the SWTDG processing is done These status codes are associated with an unplanned switch to the backup system FBEB Unplanned switch to the backup system before the ENDBCKUP program is run on the local system FBSP Unplanned switch to the backup system before the STRPROD program is run on the local system FCMP Unplanned switch to the backup system is complete (Synchronization (*SYNC) phase of the switch framework is next step) FDGD Unplanned switch to the backup system, ending data groups (ENDDG) from the production system to the backup system. FEBF Unplanned switch to the backup system, an error was detected or reported by the user when running the ENDBCKUP program on the local system FEDG Unplanned switch to the backup system, an error was detected in ENDDG or the user requested an immediate end from the DG selection program. FESW Unplanned switch to the backup system, an error was detected in SWTDG or the user requested an end from the DG selection program FSPF Unplanned switch to the backup system, an error was detected or reported by the user when running the STRPROD program on the local system FSSF Unplanned switch to the backup system, an error was detected when running the SETSWTSRC command. FSSS Unplanned switch to the backup system before setting the switch source (SETSWTSRC). FSWT Unplanned switch to the backup system before the SWTDG processing is done These status codes are associated with planned switch to the backup system BBEB Planned switch to the backup system before the ENDBCKUP program is run on the local system BBEP Planned switch to the backup system before the ENDPROD program is run on the remote system BBSP Planned switch to the backup system before the STRPROD program is run on the local system Table 12. MIMIX Model Switch Framework status codes Status codes Description MIMIX Model Switch Framework status codes 119 BCMP Planned switch to the backup system is complete (Synchronization (*SYNC) phase of the switch framework is next step) BDGD Planned switch to the backup system, ending data groups (ENDDG) from the production system to the backup system. BEBF Planned switch to the backup system, an error was detected or reported by the user when running the ENDBCKUP program on the local system BEDG Planned switch to the backup system, an error was detected in ENDDG or the user requested an immediate end from the DG selection program. BEPF Planned switch to the backup system, an error was detected or reported by the user when running the ENDPROD program on the remote system BESD Planned switch to the backup system before the end switch processing (ENDSWT). BESW Planned switch to the backup system, an error was detected in SWTDG or the user requested an end from the DG selection program BSPF Planned switch to the backup system, an error was detected or reported by the user when running the STRPROD program on the local system BSSF Planned switch to the backup system, an error was detected when running the SETSWTSRC command. BSSS Planned switch to the backup system before setting the switch source (SETSWTSRC). BSWT Planned switch to the backup system before the SWTDG processing is done These status codes are only encountered if the switch framework is set up to auto- matically start the data groups after a planned switch operation ACMP Planned switch to the backup system is complete and the data groups have been automatically started (Switch back to the original production system (*PROD) phase of the switch framework is the next step) BBSB Planned switch to the backup system before the STRBCKUP program is run on the remote system BEST Planned switch to the backup system, an error was detected in STRDG or the user requested an end from the DG selection program BSBF Planned switch to the backup system, an error was detected or reported by the user when running STRBCKUP on the remote system BSTR Planned switch to the backup system before the STRDG processing is done These status codes are associated with the synchronization phase SBSB Synchronization phase before the STRBCKUP program is run on the remote system Table 12. MIMIX Model Switch Framework status codes Status codes Description 120 SCMP Synchronization phase is complete (Switch back to the original production system (*PROD) phase of the switch framework is the next step) SEST Synchronization phase, an error was detected in STRDG or the user requested an end from the DG selection program SSBF Synchronization phase, an error was detected or reported by the user when running STRBCKUP on the remote system SSTR Synchronization phase before the STRDG processing is done Table 12. MIMIX Model Switch Framework status codes Status codes Description MIMIX Model Switch Framework user exit programs 121 MIMIX Model Switch Framework user exit programs These user exit programs are supplied to enable you to customize your switching environment. You should copy these programs and customize them for your installation. The source templates for the following user exit programs are located in file MMTEMPLSRC in the MIMIX installation library. You can access these programs and change them to address the needs of your system environment. Note: Before you make any changes to these templates, you should copy them into a different source file so the changes will not be lost if any updates are required to this template source in the future. Use the Create CL Program (CRTCLPGM) command to compile the following programs: DGSELECT - This program selects the data groups that should be switched or started. You can: • Change the value for the WAIT parameter. • Indicate if you would like to have the switch end if there are database errors. • Choose to stop the switch framework process immediately. You can do this by accessing the source for this program and changing the code so the program passes a ‘2’ for the &ENDDBERR variable. When this program is called for starting the data groups, you can select to not start the target (apply) processes for the data group. ENDBCKUP -This program ends the user's backup environment. ENDPROD - This program ends the user's production environment. STRBCKUP - This program starts the user's backup environment. STRPROD - This program starts the user's production environment. You can specify that you want to stop the switching process by accessing the source for the programs listed above and changing the code so the program sets the LDA data area to a value other than “SUCCESSFUL”. SWTFWKCFM - This program confirms that you want to start the switch framework processing. You can specify that you want to stop the switching process by accessing the source for this program and changing the code so the program passes a ‘1’ for the &RESPONSE variable. The default action of this program is to start the switching process. 122 Orphaned data and objects Orphaned data and objects are those that have not been sent to the backup system when a production system failure occurs. You can prevent orphaned data by ensuring that there are no jobs other than MIMIX currently active on the source system. To ensure this, you may need to end all interactive and batch subsystems other than those associated with MIMIX. You should also prevent your users from accessing either system until after the switch is complete and the data group is restarted. MIMIX provides journal analysis tools for user journal replication processes that can be used after an unplanned switch to identify any orphaned data. 123 CHAPTER 7 Working with the UPS monitor This section provides procedures for configuring IBM Power TM Systems for use with the UPS monitor, customizing the UPS monitor, and working with functions that are unique to the UPS monitor. The uninterruptible power supply (UPS) monitor is a predefined monitor that can assist you in the event of a power failure if the system is connected to an intelligent uninterruptible power supply. The UPS monitor is shipped with this release of MIMIX Monitor. You can use MIMIX Monitor without ever using the UPS monitor, however, you may find that the UPS monitor can play a useful role in meeting your availability management requirements. This section describes how to customize the UPS monitor to the needs of your enterprise. 124 UPS monitor highlights The UPS monitor requires that an intelligent uninterruptible power supply be connected to the system where the monitor is used. The UPS monitor also requires some initial configuration before you use standard MIMIX Monitor interfaces to activate it. When a power failure occurs and the system is running on the UPS battery backup, the UPS monitor tracks the amount of available backup power and the amount of time before the UPS will expire. The UPS monitor notifies the system operator and users of the time remaining before the UPS power drains to a level that requires that system functions be ended. The UPS monitor then performs the steps necessary to power down the system in a normal, controlled manner that reduces the likelihood of abnormal system terminations and subsequent long IPLs. Note: You may need to order and install the iSeries power warning feature and have it connected to the UPS before you use the monitor. A key concept for the UPS monitor is that of maximum UPS battery time. This is the amount of time that the system can function while running on auxiliary power from the UPS battery. This time must be greater than the time needed to prepare the system and perform a power down. With the UPS monitor, you have a degree of control over how the system is prepared for a power down and the type of power down that will occur. When you configure the UPS monitor, you can specify a series of preparation functions to perform before shutting down the system, the type of power down you want, and whether or not you want the UPS monitor to restart the system. You can also specify exit programs to call when preparing to power down the system after a power failure and exit programs to use when power is restored to the system. During configuration you can specify any combination of the following preparation functions and the order in which they occur: • Send a final warning message to users • Hold job queues • Run a failure exit program You also have the choice of the following power down options: • In a controlled power down, the system is powered down using the operating system command PWRDWNSYS OPTION(*CNTRLD). The PWRDWNSYS command uses the delay and restart values you specify during configuration. The subsystem ends all active jobs in a controlled manner. Programs running in the active jobs are allowed to perform clean up activities for the specified delay time. If the possibility exists that an active job could begin to loop or send inquiry messages to the system operator, you should specify a value for the DELAY parameter during configuration. When the system is operating on auxiliary power and the delay time specified passes the power down process begins without additional job cleanup activity. • In an immediate power down, the system is powered down using the operating system command PWRDWNSYS OPTION(*IMMED). The subsystem immediately ends all active jobs. The system value QPWRDWNLMT (maximum UPS monitor highlights 125 time for PWRDWNSYS *IMMED) controls the amount of time allowed for cleanup. Programs running in the active jobs may not be allowed to complete any cleanup activities. This may cause undesirable results if data has been partially updated. When the system is operating on auxiliary power the power down process begins without additional job cleanup activity. • In an instant power down, the system value QUPSDLYTIM (uninterruptible power supply delay time) is set to 0 and the UPS monitor is ended. The system immediately saves main storage and begins to power down. The system will act as if the battery power has expired. The system is not restarted after the power down. Through the use of a failure exit program, you can specify your own processes for ending the system prior to a power down. Similarly, you can specify a restore exit program to control activity to occur if the power is restored before the battery expires. Operator intervention: The UPS monitor is initially set so that if the monitor determines that the system must be shut down, no operator action is necessary to power down the system. Your enterprise may prefer or require that an operator intervene before the power down begins. The Request operator response (OPRRSP) parameter on the Change UPS Configuration command determines whether or not the UPS monitor sends an inquiry message to the system operator before starting the power down process. When the Request operator response (OPRRSP) is set to *NO, the power down process starts automatically. When it is set to *YES, the UPS monitor sends an inquiry message to the system operator (QSYSOPR) when the shutdown preparation sequence completes and before starting the power down process. The operator has two minutes in which to respond to the inquiry message. If the operator does not reply within two minutes, the power down process continues. An operator reply of Y (Yes) to the inquiry message continues the power down process. An operator reply of N (No) prevents the power down from starting. When the operator reply is N (No), the UPS monitor ends and no longer monitors the UPS. However, a reply of N (No) does not ensure that the system will remain active. If the battery power supply is exhausted, the system may still power down. The operating system may automatically power down the system based on the value of the QUPSDLYTIM system value. The UPS monitor also enables you to warn users at several points while the system is running on auxiliary power. You can specify a group of users to receive messages, the types of messages to send, the text of the messages, and the frequency in which they are sent. The UPS monitor can send messages when the system is initially switched to UPS power, at intervals while running on UPS power, when the power down process is about to begin, and when system power is restored. 126 Checklist: UPS configuration Before you can use the UPS monitor, you need to ensure that the system is configured appropriately and that the operating environment allows the UPS monitor to always be active. Do the following: 1. Ensure that the UPS is configured correctly and connected to the system. The uninterruptible power supply (UPS) must be configured to communicate with the system. A separate communications cable must be connected between the UPS communications interface port and the system UPS port. The system’s power must be plugged into the UPS. Refer to the operator's guide for the UPS for the steps required to configure the UPS for intelligent communications. This step is required. 2. Estimate the time needed for the system to perform the preparation functions and to perform the type of power down you want. Also determine the maximum amount of time that the system can run on the UPS battery. This step is required before you configure the UPS monitor. For more information see “Evaluating battery time requirements” on page 127. 3. Modify your startup program so that the UPS monitor remains active at all times. Refer to “Ensuring the UPS monitor is always active” on page 129. 4. Set system values so that the UPS monitor can control the power down process in the event of a power failure. This step is required. Refer to “Setting system values for the UPS monitor” on page 130. 5. Ensure that the job priority for the UPS monitor is higher than all other interactive and batch jobs. This step is required. Refer to “Setting the job priority for the UPS monitor” on page 131. 6. Configure the UPS monitor. Refer to “Configuring the UPS monitor” on page 133. 7. Start the MIMIXUPS subsystem using the command STRSBS SBSD(MIMIXUPS). 8. Start the UPS monitor by referring to “Starting a monitor” on page 42. 9. Display the status of the UPS monitor by referring to “Displaying status for the UPS monitor” on page 141. You should see that the monitor is active, UPS power should be 100 percent, and the UPS operational status should be standby. 10. Test the UPS monitor configuration by referring to “Testing the UPS configuration” on page 137. 11. Update the available UPS power by referring to “Updating the available UPS power” on page 138. 12. Test the power failure and restore processes by referring to “Testing power changes” on page 139. Evaluating battery time requirements 127 Evaluating battery time requirements You need to provide the UPS monitor with an estimate of the maximum amount of time for which the UPS (uninterruptible power supply) can provide auxiliary power. To determine this value, you need to compare the UPS manufacturer's maximum battery time to the time needed to perform the functions in the preparation sequence and power down the system. Do the following: 1. Determine the preparation time. This is an estimate, in minutes, of how much time is needed to complete the functions in the preparation sequence. The preparation sequence can include any or all of the following functions: • Send a final warning message to users • Hold all job queuesRun the failure exit program Include in your estimate all functions that you specify in the preparation sequence. The amount of time needed for these activities can only be determined by experience with your system. Be conservative in your estimates. When you configure the UPS monitor you need to provide this estimate. 2. Determine the power down time. This is a group of estimates, in minutes, of the amount of time needed to power down the system. Determine an estimate for each of the following power down options: • *CNTRLD • *IMMED • *INSTANT Note: The power down options are described on “UPS monitor highlights” on page 124. The time needed to perform each of the power down options can only be determined by experience with your system. Be conservative in your estimates. When you determine the estimate for the controlled power down (*CNTRLD) be sure to include any delay time that you specify in the configuration options. Convert the delay time from seconds to minutes when you add it to your estimate. One possible way to estimate the time needed for an immediate power down (*IMMED) is to determine how much time is needed to end all subsystems while the system is running a regular workload (the ENDSBS SBS(*ALL) OPTION(*IMMED) command). When you configure the UPS monitor you need to provide these estimates. 3. Determine the UPS manufacturer's maximum battery time. Use the tables found in the operator’s guide for the UPS to determine the maximum amount of time that the battery can power the system. Prepare your estimate with the assumption that the system will use the full amount of power available from the UPS. Be conservative in your estimates. Note: As the UPS battery ages, power will drain from an unused battery and may 128 cause the battery to expire. A drained or expired battery does not protect your system. The UPS monitor cannot determine if the battery is drained. You should periodically check the UPS indicators and recharge the battery when necessary. (You could even create a user-defined time monitor to periodically remind you to check the battery.) 4. Add the preparation time from Step 1 to the estimate for the power down option (Step 2) that you plan to use. This is the amount of time you need to prepare the system and power down. 5. Compare the manufacturer's time in Step 3 to the amount of time you need to prepare and power down the system in Step 4. If the manufacturer's time is larger, you can use either value for the maximum battery time field when you configure the UPS monitor. 6. If you need more time than the manufacturer's estimate, consider changing the activities that are specified in the preparation sequence so that they and the power down can complete before the battery expires. Ensuring the UPS monitor is always active 129 Ensuring the UPS monitor is always active If the UPS monitor is not active when a power failure occurs, the operating system will power down the system. By modifying your startup program you can ensure that the UPS monitor remains active at all times. Do the following to ensure that the system is in the proper state to run the UPS monitor: 1. Add the following commands to the end of your start up program to start the MIMIXUPS subsystem and the UPS monitor. Starting these activities ensures that the UPS monitor is started after each IPL. STRSBS SBSD( MI MI XQGPL/ MI MI XUPS) monitor-installation-libr ar y/ STRMON MONI TOR( UPSMON) 2. Ensure that you have the QUPSDLYTIM (uninterruptible power supply delay time) system value set so that it is greater to or equal to the value specified in the UPS configuration for the maximum battery time. For more information see “Evaluating battery time requirements” on page 127. 130 Setting system values for the UPS monitor You need to set three system values so that the UPS monitor can monitor the UPS message queue and can control the power down process in the event of a power failure. Do the following to set the system values: 1. Type the command WRKSYSVAL and press Enter. 2. The Work with System Value display appears. Position the list to the QPWRRSTIPL system value. Type a 2 next to the QPWRRSTIPL system value and press Enter. 3. The Change System Value display appears. Type a 1 at the Auto-IPL after power restored prompt and press Enter. This ensures that the system automatically IPLs after power is restored. 4. The Work with System Values display appears again. Position the list to the QUPSDLYTIM system value. Type a 2 next to the QUPSDLYTIM system value and press Enter. 5. The Change System Value display appears. The value of the Delay time prompt must be equal to or greater than value you specify in the UPS Configuration for the maximum battery time. Convert the value of the maximum battery time from minutes to seconds (multiply by 60) to match the units for the system value. Specify this value, or a higher number, as the value for the Delay prompt and press Enter. Note: Do not use special values *NOMAX, *CALC, OR *BASIC for this system value. If the QUPDSLYTIM system value is set to a special value or if it is less than the value specified for the maximum battery time in the UPS configuration, the UPS monitor will change the value of QUPSDLYTIM every time the UPS monitor is started. If *NOMAX is used and the QUPSMSGQ message queue is not allocated when a power failure is detected, the system will power down immediately. 6. The Work with System Values display appears. Type a 2 next to the QUPSMSGQ system value and press Enter. 7. The Change System Values display appears. Type UPSMONMQ for the Message queue prompt. Type the name of the MIMIX Monitor product library for the Library prompt. If you used the default value during installation, the library name is MIMIX. Press Enter. If the UPS monitor is not active when a power failure occurs, the operating system performs the power down process. The operating system delays the power down process by the value specified (except for *NOMAX) for the QUPSDLYTIM system value. Setting the job priority for the UPS monitor 131 Setting the job priority for the UPS monitor For the UPS monitor to function quickly and efficiently, the run priority of its job must be a higher priority than all other interactive and batch jobs. A run priority of 10 should be sufficient. When the UPS monitor is not performing a function, it switches into a delay mode which reduces the potential overhead of a continuous polling request. Do the following to verify the run priority for the UPS monitor job: 1. Type the command WRKACTJOB and press Enter. 2. The Work with Active J obs display appears. Press Page Down to locate the MIMIXUPS subsystem and the UPSMON job. 3. Type a 2 (Change) next to the UPSMON job and press Enter. 4. The Change J ob (CHGJ OB) display appears. Verify the value of the Run priority (RUNPTY) parameter. 5. If the value is 10 or less than 10, you do not need to change the run priority. Press F12 (Cancel). 6. If the value is greater than 10, you should change the run priority to 10 or less than 10. Higher numbers indicate a lower run priority. A lower run priority may not allow the UPS monitor to have the required responsiveness. When you are ready, press Enter. 132 Accessing the UPS monitor menu The UPS Monitor Menu enables you to access options that are unique to the UPS monitor. There are multiple ways to access the UPS Monitor Menu. From the MIMIX Basic Main Menu, do the following: 1. Select option 12 (Work with monitors) and press Enter. 2. The Work with Monitors display appears. Type option 12 (Work with) next to the entry for the UPSMON and press Enter. From the MIMIX Intermediate Main Menu, do the following: 1. Select option 13 (Utilities menu) and press Enter. 2. From the MIMIX Utilities Menu, select option 71 (UPS monitor menu) and press Enter. You can also access the UPS Monitor menu from a command line. Specify the name of the MIMIX installation library in the following command and press Enter: GO installation_library/ MMUPSMENU Configuring the UPS monitor 133 Configuring the UPS monitor To configure the UPS monitor for use, do the following: 1. From the UPS Monitor Menu, select option 10 (Change UPS monitor configuration) and press Enter. 2. The Change UPS Configuration (CHGUPSCFG) display appears. When you are configuring the UPS monitor for the first time, you should specify all options. If you are updating an existing configuration, specify only the options you need to change. Consider the following options: a. Specify the value to use for the Maximum battery time (min.) prompt. For more information see “Evaluating battery time requirements” on page 127 b. At the Preparation Sequence prompts, specify a number to indicate the order in which each of the preparation functions occurs. The value 1 indicates that the function is performed first. The value *NO indicates that the function is not performed. If *NONE is specified for the Failure exit program parameter, specify *NO for the Run failure exit program prompt. c. At the Preparation time (min.) prompt, specify a value that will cover all of the preparation functions you selected. Ensure that the value you specify is also reflected in the maximum battery time. d. To automatically start customized processes in the event that the UPS monitor detects a power failure, specify the name of the Failure exit program and the library in which it is located. Note: You must specify to run the failure exit program in the preparation sequence. e. Specify the value for the type of power down you want at the Power down option prompt. The power down options are described on “UPS monitor highlights” on page 124. f. Specify a value for each of the Power down times (min.) prompts. Ensure that the value you specify is also reflected in the maximum battery time. 3. Press Enter. Additional parameters appear on the display. 4. Specify the following options, as needed: a. If you specified *CNTRLD for the Power down option, specify the amount of time, in seconds, in which a controlled end can be performed in the Delay time, if *CNTRLD prompt. The system allows this amount of time for active subsystems to perform a controlled end. If the end-of-job routines are not finished in the specified time, any remaining jobs are ended immediately. If you specify a large value, the power down may not complete before the power supply is depleted. b. Specify the option you want for the Restart after power down prompt. The value *NO causes the system to end and power down. The system is not restarted automatically. The value *YES causes the system to end and start again in unattended mode. If the system is running on utility power, the system undergoes end of processing and, instead of powering down, the system 134 performs an abbreviated IPL. If the system is running on auxiliary power, the system powers down. Then, when utility power is restored, the system performs an automatic IPL if the QPWRRSTIPL system value (automatic IPL after power restored) is set to 1. The IPL proceeds in an unattended mode. c. Specify the value you want for the Send initial warning message prompt. The value *YES sends a message when the system switches to auxiliary power from the UPS. d. Specify a delay time, in minutes, for the Warning delay interval prompt. A value of 0 indicates that no interval warning messages are sent. e. Specify the value you want for the Send restore message prompt. f. Specify the value you want for the To user profile prompt. g. To automatically start customized restore exit programs when the power is restored, specify the name of the Restore exit program and the library in which it is located. h. To have the UPS monitor display an inquiry message that allows the system operator the possibility of preventing the power down, specify *YES at the Request operator response prompt. If the operator does not respond to the message within two minutes, the power down continues. i. To change the Job description used to submit UPS monitor jobs, specify the name of the job description you want and the library in which it is located. 5. To accept changes to any of the prompts on the Change UPS Configuration display, press Enter. Changing warning message text 135 Changing warning message text You can change the text of any or all of the warning messages that are sent to users. To change the text of warning messages sent to users, do the following: 1. From the UPS Monitor Menu, select option 11 (Change UPS messages) and press Enter. 2. The Change UPS Message (CHGUPSMSG) display appears. Specify the message type for which you want to modify text and press Enter. 3. The text of the default message appears. The first-level text is the message text. The second-level text is what appears when the user requests the Help function on the message. Text must appear within apostrophes (‘). Use F1 (Help) to determine additional formatting restrictions for the first- and second-level text fields. 4. In your message text, you should identify why the message was sent and what action is expected from the user. If you require user action, you may also want to indicate the consequences of not taking the requested action. The UPS monitor appends an eight-character field to the end of the second-level text. This field includes the current number of minutes remaining in which the UPS power can run the system. Be sure to allow enough space for this field. 5. When you are ready to accept the changes you made, press Enter. 136 Starting and ending the UPS monitor The UPS monitor uses the standard interface for starting (option 9) and ending (option 10) monitors from the Work with Monitors display. Occasionally you may need to end the UPS monitor. If you do not want to have the UPS monitor control the system shutdown in the event of a power failure, you need to end the UPS monitor. You also need to end the UPS monitor when you upgrade your installation of MIMIX Monitor. Testing the UPS configuration 137 Testing the UPS configuration When you test the configuration for the first time, consider testing the configuration during off-peak hours. To test that the UPS monitor and the UPS are correctly configured; do the following: 1. Display the status of the UPS monitor. Refer to “Displaying status for the UPS monitor” on page 141. 2. Unplug the UPS from the power source. 3. Press F5 (Refresh) on UPS Monitor Status display. The operational status should change to running and the power status should update the percentage of power that is available. 4. Plug the UPS into the power source before all the battery power is used. DANGER Up to 240 V ac is present at the power source. To prevent a possible electrical shock from touching two surfaces with different electrical grounds, use one hand, when possible, to connect or disconnect cables. An electrical outlet that is not correctly wired could place hazardous voltage on metal parts of the system or products attached to the system. It is the customer’s responsibility to ensure that the outlet is correctly wired and grounded to prevent an electrical shock. 138 Updating the available UPS power The system cannot indicate whether the UPS is fully charged. You need to provide the UPS monitor with an estimate of the percentage of power available from the UPS. The UPS monitor uses this value as the base from which all other power availability estimates are based. If the percentage of available UPS power, as defined to the UPS monitor, is below 100% when the monitor is started, the MIMIX message queues and log are notified. You should update the percentage of power available from the UPS in the following situations: • During the initial configuration of the UPS monitor • After the UPS battery has recharged itself, either after restoring power or after simulating a power change. If you do not update the percentage of power available from the UPS, the next power down may start earlier than necessary because the UPS monitor is using the value remaining from the previous power down. Do the following to update the UPS availability percentage: 1. Determine the percent of charge for the UPS battery by looking at the indicators on the UPS. 2. When the battery is fully charged, select option 12 (Update UPS availability) from the UPS Monitor Menu and press Enter. 3. The Update UPS Power Availability display appears. Type the appropriate number for the New percentage of full power available prompt and press Enter. Note: To automate this change as part of a program, you can use the Change UPS Availability (CHGUPSAVL) command. Testing power changes 139 Testing power changes You can simulate power changes to test the operation of the UPS monitor and the processes used to shut down the system. Both power failure and power restore operations can be simulated with the Test Power Change (TSTPWRCHG) command. It is possible to power down the system with this test. Do the following to simulate a power failure and power restore sequence: 1. From the UPS Monitor Menu, select option 3 (Display UPS monitor status) and press Enter. 2. The UPS Monitor Status display appears. Make a note of the value shown for Approximate time remaining, then press F12 (Cancel). ________________Approximate Time Remaining 3. From the UPS Monitor Menu, select option 10 (Change UPS monitor configuration) and press Enter 4. The Change UPS Configuration display appears. Make a note of the following information: a. Which of the functions of the Preparation sequence parameter are selected: Send final message _____________ Hold job queues ______________ Run failure exit program ______________ b. The time specified for preparation: _____________ c. Which power down option is specified: ____________ d. The power down time for the specified power down option: _________ e. The value specified for the Restart after power down prompt _____ 5. Add the values for the preparation time and the power down time for the selected power down option. (Step 4b +Step 4d =____). Compare this value to the approximate time remaining (Step 2). The approximate time remaining should exceed the sum of the shutdown sequence and selected power down option. Do not continue with the power change test if the approximate time remaining for the UPS is not sufficient to complete the preparation sequence functions selected and the specified power down option. 6. On the Change UPS Configuration display, do the following: a. Press F9 (All parameters) then press Page Down to see additional options on the second display. b. Verify that Request operator response prompt is set to *YES. If necessary, change the value to *YES and press Enter. This will ensure that an inquiry message is sent to the system operator before the power down command is processed, allowing you the opportunity to stop the power down. You can reset this value after the test completes if you do not want operator intervention during a real power down. 140 7. From the UPS Monitor Menu, select option 20 (Test power failure) and press Enter. 8. You will see status messages in the system operator message queue (QSYSOPR). You will also see either break messages or messages in your message queue, depending on the value of the configuration option To user profile. 9. You can stop the power failure test at any time by selecting option 21 (Test power restore) from the UPS Monitor Menu and pressing Enter. Note: Starting the power restore test stops the power failure test. If you wait to start the power restore test until after the final warning message is sent, the restore request may not be received, causing the system to power down. 10. If the Request operator response prompt was set to *YES you will see an inquiry message. You have two minutes in which to respond to the inquiry message. A response of N (No) prevents the power down and ends the UPS monitor. Note: If you do not respond within two minutes or if you respond with Y (Yes), the system will be powered down. 11. After power is restored successfully or after the restore power test completes, ensure that the UPS battery is recharged to 100%. 12. Update the new percentage of full available power using the instructions in “Updating the available UPS power” on page 138. 13. If necessary, restart the UPS monitor. Displaying status for the UPS monitor 141 Displaying status for the UPS monitor From the UPS Monitor Status display, you can quickly determine the status of the UPS monitor and the status of UPS power. You can also determine whether the system is running on UPS power, when UPS power was activated, what type of power down will be performed if needed, and the expected start time for power down preparation activities. You can display the status of the UPS monitor in several ways. You can use standard option (15) from the Work with Monitors display, or you can use the following procedure or fast path command. The results are the same for all methods. Do the following to display status of the UPS monitor: 1. Do one of the following: • If you are already on the Work with Monitors display, type option 15 (Status) next to the UPSMON entry and press Enter. • Use any of the procedures described in “Accessing the UPS monitor menu” on page 132. Then, from the UPS Monitor Menu, select option 3 (Display UPS monitor status) and press Enter. 2. The UPS Monitor Status display appears. When you verify the configuration of the UPS monitor, you should see that the UPS monitor is active, the battery should be charged to 100%, and the UPS operational status should be on standby. 3. To set this display to automatically refresh the status, type a number between 5 and 999, specified in minutes, in the Auto refresh prompt and press F9 (Automatic refresh). Figure 9. UPS monitor status. In Figure 9 the UPS battery is not charged to 100%. SYSTEMA UPS Moni t or St at us 02/ 19/ 99 19: 23: 51 = I nact i ve/ Runni ng Aut o r ef r esh ___ = Act i ve/ St andby = Unknown UPS Power St at us Maxi mumt i me f or UPS power : 60 ( Mi nut es) Amount of t i me used . . . . : 45 Moni t or ====== Act i ve Appr oxi mat e t i me r emai ni ng . : 15 UPS Oper at i onal St at us UPS st at us . . . . . . . . . . . . : St andby Cur r ent st at us . . . . . . . . . . : Power down opt i on sel ect ed . . . . : PWRDWNSYS ( *CNTRLD) DATE TI ME . Act i vat i on . . . . . . . . . . . . : St ar t of shut down sequence . . . : Appr oxi mat e st ar t of power down . . : F3=Exi t F5=Ref r esh F9=Aut omat i c r ef r esh F12=Cancel 142 On this display the following colors are assigned to these statuses: Red (Inactive/Running). Red indicates that the UPS monitor is inactive, that the UPS battery is running the system, or that the UPS power is not fully charged. Blue (Active/Standby). Blue indicates that the UPS monitor is active, that the UPS is on standby, or that power is fully available. White (Unknown). White indicates that the status of the UPS monitor or of the UPS could not be determined. The UPS Operational Status box and the UPS Power Status box are white when the monitor is inactive. For more information about the status indicators, press F1 (Help). Changing the UPS subsystem 143 Changing the UPS subsystem The UPS monitor runs in its own subsystem, MIMIXUPS. If you want to change the UPS monitor (UPSMON to the controlling subsystem, do the following: 1. End the UPS monitor using “Ending a monitor” on page 43. 2. End the MIMIXUPS subsystem by typing the command ENDSBS SBS(MIMIXUPS) OPTION(*IMMED) and pressing Enter. 3. Use the ADDJ OBQE and ADDRTGE commands to create entries for the UPS monitor under the controlling subsystem. Specify the appropriate sequence number. Note: In the following examples, the sequence number 10 is used and the controlling subsystem is QBASE. To determine the controlling subsystem, display the system value QCTLSBSD. For example: ADDJ OBQE SBSD( *LI BL/ QBASE) J OBQ( MI MI XQGPL/ MI MI XUPS) MAXACT( 1) SEQNBR( 10) ADDRTGE SBSD( *LI BL/ QBASE) SEQNBR( 10) CMPVAL( MI MI XUPS) PGM( QSYS/ QCMD) CLS( MI MI XQGPL/ MI MI XUPS) 4. Start the UPS monitor using “Starting a monitor” on page 42. 5. Verify that the UPS monitor is running under the controlling subsystem by using the WRKACTJ OB command. Removing the UPS monitor from the controlling subsystem To remove the UPS monitor from the controlling subsystem, do the following: Remove the job queue entry and the routing entry from the controlling subsystem using the following commands: RMVJ OBQE SBSD( *LI BL/ QBASE) J OBQ( MI MI XQGPL/ MI MI XUPS) RMVRTGE SBSD( *LI BL/ QBASE) SEQNBR( 10) Note: In this example, QBASE is the controlling subsystem and sequence number 10 is the sequence number for the UPS monitor. Programming for monitors 144 CHAPTER 8 Programming for monitors This section describes the programming requirements for condition programs, event programs, and interface exit programs that are called by monitors. This section also describes the application programming interface (API) provided with MIMIX Monitor. This section describes the required parameters and data formats for condition programs, event programs, and interface exit programs. If you need to have your condition program or event program retrieve information from MIMIX Monitor, you can include calls to the MIMIX Monitor User Access API. A header file is available for inclusion in C/400 programs and resides in the product library in source file H. The header file name is MMUSRACCS and contains #define statements for each event class and for each MIMIX Monitor User Access (MMUSRACCS) API format, data structures for each format, and data structures for the returned monitor information for each event class. Additionally a #program statement is defined for the program interface call to the MMUSRACCS API. Adding messages to the MIMIX message log 145 Adding messages to the MIMIX message log The Add Message Log Entry (ADDMSGLOGE) command allows you to add an entry to the MIMIX message log. This is helpful when you want to include messages from your automation programs into the MIMIX message log for easier tracking. To see the parameters for this command, type the command and press F4 (Prompt). Help text for the parameters describe the options available. The message is written to the message log file. The message is also sent to the primary and secondary messages queues if the message meets the filter criteria for those queues. The message can also be sent to a program message queue. Messages generated on a network system will be automatically sent to the management system. However, messages generated on a management system may not be sent to any network systems. The system manager on the management system does not send messages to network systems when it cannot determine which system should receive the message. 146 What to include in your programs The content of your user-defined programs is a key component of an effective monitor. What you intend to accomplish with a monitor will determine what type of information you need to include. This information describes content for common monitoring scenarios. Programming for switching For switching operations, determine how much of the switching operation you want to automate via programming or if you want to perform part of the switch manually. The event program defined in the switch definition and called by the group monitor controls the switch. To automate the switch, your program should include the following commands: • Set Switch Source (SETSWTSRC) • Start Switch Screen (STRSWTSCN) • Change Switch Definition (CHGSWTDFN)--to change the switch logon message If you are planning on using a switch to change the direction of replication for MIMIX, you need to include the MIMIX commands for switching the data group. Refer to the MIMIX Operations book for information about switching data groups. For additional information on switches refer to “Working with switch definitions” on page 79. Programming for the UPS monitor The UPS monitor allows for user-defined programming through the use of a failure exit program and a restore exit program. The use of each program is optional, however you can use them to enhance the effectiveness of the UPS monitor in the event that a loss of power causes the system to power down. There are no parameters for the failure exit program and the restore exit program. In the failure exit program, you may want to include commands to shut down or quiesce your applications in an orderly manner. If you use the restore exit program, you may want to include your startup program. For more information about monitor functions refer to “Working with the UPS monitor” on page 123. Interface exit program 147 Interface exit program If you write an interface exit program to perform additional processing of objects associated with the monitor definition, you must include the following parameters. Required parameters Monitor INPUT; CHAR(10) This is the name of the monitor with which this program is associated. Event class INPUT; CHAR(10) The type of event class for the monitor. Possible values are. Option INPUT; CHAR(4) Identifies the action that called the interface exit program for the monitor. The exit pro- gram was called either by a command or by an option on the Work with Monitors dis- play. *MSGQ The monitor is triggered when a specified message queue receives a predetermined message. *INTERVAL The monitor is triggered when the specified time interval has passed. *TIME The monitor is triggered at a specified time. Time can by specified either by scheduled date or scheduled day. *J RN The monitor is triggered when the specified journal receives a predetermined journal entry code or entry type. *GROUP The monitor is triggered when the last monitor that belongs to the group has a status of FAILED or FAILED/ACT. 0100 The exit program was called either by option 1=Create or by the Create Monitor Object (CRTMONOBJ ) command. 0200 The exit program was called either by option 2=Change or by the Change Monitor Object (CHGMONOBJ ) command. 0300 The exit program was called either by option 3=Copy or by the Copy Monitor Object (CPYMONOBJ ) command. 0400 The exit program was called either by option 4=Delete or by the Delete Monitor Object (DLTMONOBJ ) command. 0500 The exit program was called either by option 5=Display or by the Display Monitor Object (DSPMONOBJ ) command with OUTPUT(*) specified. 0600 The exit program was called either by option 6=Print or by the Display Monitor Object (DSPMONOBJ ) command with OUTPUT(*PRINT) specified. 0700 The exit program was called either by option 7=Rename or by the Rename Monitor Object (RNMMONOBJ ) command. 0900 The exit program was called either by option 9=Start or by the Start Monitor (STRMON) command. 1000 The exit program was called either by option 10=End or by the End Monitor (ENDMON) command. 148 Note: Option 20, CHGMONSTS STATUS(*ENABLED) command, and option 21, CHGMONSTS STATUS(*DISABLED), do not call the interface exit program. Pre- or post-call INPUT; CHAR (1) Indicates whether the interface exit program is being called before or after the requested action. Return codes OUTPUT; CHAR (1) Indicates whether the interface exit program ran successfully. The following are valid return codes: Exception ID OUTPUT; CHAR(7) A user-defined message ID that is sent to the message log. The exception ID should provide meaningful information to the person who maintains the monitor. The monitor does not use the exception ID. 1200 The exit program was called either by option 12=Work with or by the Work with Monitor Information (WRKMONINF) command. When this option is used, the interface exit program is called only as a pre-process program before the requested action. 1300 The exit program was called either by option 13=Hold or by the Hold Monitor (HLDMON) command. 1400 The exit program was called either by option 14=Release or by the Release Monitor (RLSMON) command. 1500 The exit program was called either by option 15=Status or by the Display Monitor Status (DSPMONSTS) command with OUTPUT(*) specified. 1550 The exit program was called either by option 15=Status and prompting to change OUTPUT to *PRINT, or by the Display Monitor Status (DSPMONSTS) command with OUTPUT(*PRINT) specified. 1800 The exit program was called either by option 18=Run or by the Run Monitor (RUNMON) command. 3900 The exit program was called either by option 39=Export or by the Export Monitor Object (EXPMONOBJ ) command. 4000 The exit program was called by the Import Monitor Object (IMPMONOBJ ) command. 0 The interface exit program is called in pre-processing before the requested command is processed. 1 The interface exit program is called in post-processing after the requested command is processed. 0 The interface exit program ran successfully. 1 The interface exit program did not complete successfully. Do not continue to process the requested command. This value is only evaluated when the exit program runs in pre-processing. However, it is recommended that the appropriate value be returned for both pre- and post-exit calls to enable potential future evaluation. Condition program 149 Condition program If you write a condition program to do additional condition checking, you must include the following parameters. Required parameters Monitor INPUT; CHAR(10) The name of the monitor that triggered this program call. Event class INPUT; CHAR(10) The type of event class for the monitor. Possible values are: Detailed information INPUT; CHAR(*) Provides the predefined condition information that caused the condition program to be called. The value of the monitor type parameter determines the content of this parameter. For a description of the format of the detailed information for each monitor type, see “Additional data structures” on page 156. Return code OUTPUT; CHAR(1) The following are valid return codes: If a value other than 0 is specified for the Retry attempts (RETRY) parameter of the monitor definition, the condition program will be called multiple times and the condi- tion must be met for the number of retry attempts before the event program is called. If the condition program does not return 0 (conditions have been met) the retry coun- ter will be reset to try again for the specified number of times. *MSGQ The monitor is triggered when a specified message queue receives a predetermined message. *INTERVAL The monitor is triggered when the specified time interval has passed. *TIME The monitor is triggered at a specified time. Time can by specified either by scheduled date or scheduled day. *J RN The monitor is triggered when the specified journal receives a predetermined journal entry code and entry type. *GROUP The monitor is triggered when the last monitor that belongs to the group has a status of FAILED or FAILED/ACT. 0 The condition program completed successfully. The conditions have been met. The event program is called, if one exists 1 The condition program failed or the condition was not met. The event program is not called and the monitor remains active. For group monitors, the condition program defined to the group monitor failed or the condition was not met. The status of the group monitor changes to inactive. 150 Event program If you write an event program to process the event that occurred, you must include the following parameters. Required parameters Monitor INPUT; CHAR(10) The name of the monitor that triggered this program call. Event class INPUT; CHAR(10) The type of event class for the monitor. Possible values are: Detailed information INPUT; CHAR(*) Provides the predefined condition information that caused the event program to be called. The value of the monitor type parameter determines the content of this parameter. For a description of the format of the detailed information for each monitor type see “Additional data structures” on page 156. Return code OUTPUT; CHAR(1) The following are valid return codes: *MSGQ The monitor is triggered when a specified message queue receives a predetermined message. *INTERVAL The monitor is triggered when the specified time interval has passed. *TIME The monitor is triggered at a specified time. Time can by specified either by scheduled date or scheduled day. *J RN The monitor is triggered when the specified journal receives a predetermined journal entry code and entry type. *GROUP The monitor is triggered when the last monitor that belongs to the group has a status of FAILED or FAILED/ACT. 0 The event program completed successfully. The monitor remains active. For a group monitor, the associated event program completed successfully. Status for the group monitor changes to INACTIVE. 1 The event program failed and the monitor remains active. The status of the monitor will change to FAILED/ACT. If the monitor participates in a group, the group monitor is active, and this monitor is the last monitor in a group to go to a failed status (FAILED or FAILED/ACT), the monitor may trigger the group monitor to run its condition and event program. If the event program is defined to a group monitor, the event program failed. Status of the group monitor is changed to FAILED. 2 The event program failed and the monitor does not remain active. The status of the monitor is changed to FAILED. Event program 151 Exception ID OUTPUT; CHAR(7) A user-defined message ID that is sent to the message log. The exception ID should provide meaningful information to the person who maintains the monitor to determine what may have occurred in the event program. The monitor does not use the excep- tion ID. 152 MIMIX Monitor User Access API The MIMIX Monitor User Access (MMUSRACCS) API can be called from condition and event programs to retrieve information from MIMIX Monitor. The MMUSRACCS API is the only way in which a monitor can retrieve monitor specific information from a program. MMUSRACCS member MIMIX Monitor ships a header (H) file which includes the MMUSRACCS member. You can use this file in a C program to define the structures returned by the MMUSRACCS API. The include file is in the product installation library. If you create a C program to retrieve the information about a monitor object you can include the MMUSRACCS include file to define the structures returned by the MMUSRACCS API. Authorities and locks Service program lock: *SHRRD Service program authority: *USE Required parameters Monitor information OUTPUT; CHAR(*) This is the variable in which to receive the monitor information that is returned. The information is returned in the format specified by the format name parameter. The amount of data returned is determined by the value of the length of monitor informa- tion parameter. Users need to allocate space large enough for this parameter. Length of monitor information INPUT: BINARY(4) The size of the area to contain the monitor information, specified in bytes. The mini- mum size that can be specified is 8 bytes. This parameter must specify the size of the variable you use for the monitor informa- tion parameter. If the size specified is longer than the length of the data actually returned other parts of storage could be overwritten when this API returns the infor- mation. Format name INPUT; CHAR(7) This is the format in which to return the monitor information. The supported format names are: MON0100 Returns basic information. See “MON0100 format” on page 153. for details. MIMIX Monitor User Access API 153 Monitor name INPUT;CHAR(10) This is the name of the monitor for which information is being requested. This parameter is not currently used. Monitor type INPUT;CHAR(10 The type of event class of the monitor specified in the Monitor name parameter. Pos- sible values are: Error code INPUT/OUTPUT;CHAR(*) This is the structure in which to return error information. If this parameter is omitted, null, or if the bytes provided are less than or equal to 8, escape messages are sent to the calling program. For more information about error code structures, refer to IBM API Programming information. MON0100 format This format is used in the “Format name” parameter. MON0200 Returns all monitor status information from the last call to the event program. See “MON0200 format” on page 154 for details. *MSG The monitor is triggered when a specified message queue receives a predetermined message. *INTERVAL The monitor is triggered when the specified time interval has passed. *TIME The monitor is triggered at a specified time. Time can by specified either by scheduled date or scheduled day. *J RN The monitor is triggered when the specified journal receives a predetermined journal entry code or entry type. *GROUP The monitor is triggered when the last monitor that belongs to the group has a status of FAILED or FAILED/ACT. Table 13. MON0100 format Offset Dec Hex Type Field 0 0 BINARY(4) Bytes returned 4 4 BINARY(4) Bytes available 8 8 CHAR(1) Event program successful flag 9 9 CHAR(1) Shutdown set flag 10 A CHAR(10) Monitor status 154 MON0200 format This format is used in the “Format name” parameter. Field descriptions Bytes available. This is the length of all available information that could be returned for the selected format. The value of this field can be greater than the length specified in the Length of monitor information parameter. If the length of this field is greater than the value specified in the Length of monitor information parameter, the data returned in the monitor information parameter is truncated to the length of this field. Bytes provided. The number of bytes that the calling application provides for the error code. If the API caller is using format ERRC0100, the bytes provided must be 0,8, or more than 8. If more than 32 783 bytes (32KB for exception data plus 16 bytes for other fields) are specified, it is not an error, but only 32 767 bytes (32KB) can be returned in the exception data. Bytes returned. This is the length of all available information that is returned in the specified format. The value of this field is always less than or equal to the value of the Length of monitor information parameter. If the value is less than the value of the Length of monitor information parameter, the extra space in the monitor information parameter is unchanged. The Bytes returned value is also always less than or equal to the value of the Bytes available field, with one exception. The exception occurs when you attempt to receive information about a monitor that does not exist. When a monitor does not exist, the Bytes returned field is 8 and the Bytes available field is 0. The remaining fields are unchanged and contain whatever value was already stored. Table 14. MON0200 format Offset Dec Hex Type Field 0 0 BINARY(4) Bytes returned 4 4 BINARY(4) Bytes available 8 8 CHAR(1) Event program successful flag 9 9 CHAR(1) Shutdown set flag 10 A CHAR(10) Monitor status 20 14 CHAR(20) Reserved 40 28 CHAR(*) Monitor detailed information The monitor type determines the structure of this field. See “Additional data structures” on page 156. MIMIX Monitor User Access API 155 Event program successful flag. This flag indicates the success of the event program for this monitor on the last time the program was run. Possible values are: Exception data. A variable-length character field that contains the insert data associated with the exception ID. Exception ID. The identifier for the message for the error condition. Monitor detail information. This is the detailed information for this monitor. The structure of this information varies for each event class of monitor. For detailed information, see “Additional data structures” on page 156. Monitor status. Indicates the status of the monitor at the time the API was called. Possible values are: Reserved. This field is reserved for future use or enhancement. Shutdown flag. This flag indicates whether or not this monitor has shutdown or is being shutdown. Possible values are: Y The last time the event program ran, it ran successfully and returned a value of 0. N The last time the event program ran, it ran unsuccessfully and returned a value other than 0. STARTING The monitor job is starting or is in the process of being started. ACTIVE The monitor is currently active. SCHEDULED The monitor is scheduled. A job scheduled entry exists for the monitor in the IBM i job scheduler. This value only applies to *TIME monitors. HELD The monitor is currently being held. INACTIVE The monitor is not currently active. ENDING The monitor job is ending or is in the process of becoming inactive. DISABLED The monitor has been disabled. If the monitor belongs to a group it will not participate in the triggering of the group. FAILED/ACT The monitor has failed but remains active. The event program for the monitor requested that the monitor status be set to failed but the monitor remains active. If the monitor belongs to a group it will participate in the decision to trigger the group. FAILED The monitor has failed. Either the event program for the monitor requested that the monitor be ended and the status set to failed, an unexpected error occurred in the monitor, or the maximum number of restarts have been attempted. If the monitor belongs to a group it will participate in the decision to trigger the group. Y The monitor has been instructed to shutdown. The monitor is either inactive, or is in the process of shutting down. N The monitor has not been instructed to shutdown. 156 Additional data structures This information shows the data formats used in programming for a monitor. The fields for all formats are described in “Field descriptions” on page 154. Detail information format Each type of event class has its own structure for detailed information. The detailed information format is used in the following places: • Condition program: detailed information parameter • Event program: detailed information parameter • MMUSRACCS API: format name parameter, monitor detailed information field used in format MON0200.Message Queue (*MSGQ) Message Queue (*MSGQ) The following information is returned if you specified *MSGQ for the Monitor type parameter in the MIMIX Monitor User Access (MMUSRACCS) API. Table 15. Message queue (*MSGQ) information Offset Dec Hex Type Field 0 0 CHAR(20) Message queue and library names 20 14 CHAR(7) Message ID 27 1B CHAR(2) Message type 29 1D CHAR(4) Message key 33 21 CHAR(3) Reserved 36 24 BINARY(4) Message data length 40 28 CHAR(256) Message data 296 128 BINARY(4) Severity 300 12C CHAR(20) Message file and library 320 140 CHAR(10) Sending job name 330 14A CHAR(10) Sending user profile 340 154 CHAR(6) Sending job number 346 15A CHAR(12) Sending program name 358 166 CHAR(10) Receiving program name 368 170 CHAR(7) Sending date 375 177 CHAR(6) Sending time Additional data structures 157 Interval (*INTERVAL) The following information is returned if you specified *INTERVAL for the Monitor type parameter in the MIMIX Monitor User Access (MMUSRACCS) API. Journal (*JRN) The following information is returned if you specified *J RN for the Monitor type parameter in the MIMIX Monitor User Access (MMUSRACCS) API. 381 17D CHAR(3) Reserved 384 180 CHAR(10) Monitor job name 394 18A CHAR(10) Monitor user profile 404 194 CHAR(6) Monitor job number 410 19A CHAR(70) Reserved Table 15. Message queue (*MSGQ) information Offset Table 16. Interval (*INTERVAL) information Offset Dec Hex Type Field 0 0 CHAR(10) Monitor job name 10 A CHAR(10) Monitor user name 20 14 CHAR(6) Monitor job number 26 1A BINARY(4) Communications flag 30 1E CHAR(10) Communications subclass 40 28 CHAR(264) Reserved Table 17. J ournal (*J RN) information Offset Dec Hex Type Field 0 0 CHAR(20) J ournal and library names 20 14 CHAR(170) J ournal header information 190 BE CHAR(256) J ournal entry data 446 1BE CHAR(10) Monitor job name 456 1C8 CHAR(10) Monitor user profile 158 Time (*TIME) The following information is returned if you specified *TIME for the Monitor type parameter in the MIMIX Monitor User Access (MMUSRACCS) API. Group (*GROUP) The following information is returned if you specified *GROUP for the Monitor type parameter in the MIMIX Monitor User Access (MMUSRACCS) API. 466 1C2 CHAR(6) Monitor job number 472 1D8 CHAR(20) Last sequence number 492 1EC CHAR(20) J ournal receiver of last sequence number processed 512 200 CHAR(20) Previous journal receiver 532 214 CHAR(20) Current journal receiver 552 228 CHAR(1) Abnormal end of monitor 553 229 CHAR(1) Process J NR entry 554 22A CHAR(1) Process J PR entry 555 22B CHAR(1) Process J codes 556 22C CHAR(206) Reserved Table 17. J ournal (*J RN) information Offset Table 18. Time (*TIME) information Offset Dec Hex Type Field 0 0 CHAR(6) J ob schedule entry number 6 6 CHAR(2) Reserved 8 8 BINARY(4) Frequency once flag 12 C CHAR(244) Reserved Table 19. Group (*GROUP) information Offset Dec Hex Type Field 0 0 CHAR(10) Monitor job name 10 A CHAR(10) Monitor user profile Additional data structures 159 Error code structure This error code structure is used in the MMUSRACCS API for the Error code parameter. 20 14 CHAR(6) Monitor job number 26 1A BINARY(4) Run group monitor 30 1E BINARY(4) Group processed 34 22 CHAR(270) Reserved Table 19. Group (*GROUP) information Offset Table 20. MMUSRACCS API error code structures Offset Dec Hex Use Type Field 0 0 Input BINARY(4) Bytes provided 4 4 Output BINARY(4) Bytes available 8 8 Output CHAR(7) Exception ID 15 F Output CHAR(1) Reserved 16 10 Output CHAR(*) Exception data 160 Field descriptions The field descriptions described in this information are used in the following places: • Condition program: detailed information parameter • Event program: detailed information parameter • MMUSRACCS API: format name parameter, monitor detailed information field used in format MON0200. Communications flag: Indicates the success of the last communications check. The possible values and their meanings are: Communications subclass: The subclass of communications being checked. The possible values are: *NONE - no subclass *CFG - configuration *TCP - TCP/IP *SYSDFN - system definition *TFRDFN - transfer definition Job schedule entry number: The entry number assigned by the IBM i job scheduler. Journal and library names: The name of the journal to monitor and the library in which the journal is located. The first ten characters are the journal name and the last ten characters are the library name. Journal entry data: The first 256 bytes of the journal entry data for the transaction that was received by the monitor. If you need to retrieve all of the data from the transaction, use the Retrieve J ournal Entry (RTVJ RNE) command and specify the RTNJ RNE parameter. Journal header information: The fixed-length portion of the type 4 journal entry. For more information, refer the J ournal Entry Information appendix in the IBM book “Backup and Recovery - Advanced.” Journal receiver of last sequence number processed: The qualified name of the journal receiver that received the last processed journal entry from which the monitor is currently receiving journal transactions. Last sequence number processed: The sequence number of the last received transaction that was processed by the monitor. Not all transactions are received. Message data: The substitution data for the message data fields (variables) for the message received by the monitor. Message data length: Indicates the length of the substitution data returned in the message data field. 0 False 1 True Field descriptions 161 Message file and library: The source of the message ID that was received. The first ten characters indicate the name of the message file that contains the message ID. The last ten characters indicate the name of the library that contains the message file. Because the library can contain override instructions, the library name is not necessarily the library in which the message file actually resides. Message ID: The identifying code of the message that was received. Message key: The key to the message that was received. This field can be used to retrieve the message if it has not been removed by another process that is not part of MIMIX Monitor. Message queue and library names: The name of the message queue to monitor and the library in which the message queue is located. The first ten characters indicate the message queue name and the last ten characters indicate the library name. Message type: The message type of the message that was received. The possible values and their meanings are: Monitor job name: The name of the monitor job. Monitor job number: The job number associated with the monitor job. Monitor user profile: The name of the user profile that submitted the monitor job. Receiving program name: The name of the program that received the message. Reserved: This field is ignored. Table 21. Message types Value Message type 01 Completion (*COMP) 02 Diagnostic (*DIAG) 04 Information (*INFO) 05 Inquiry (*INQ) 06 Sender’s copy (*COPY) 08 Request (*RQS) 10 Request with prompting (*RQS) 14 Notify (*NOTIFY) 15 Escape (*ESCAPE) 21 Reply, not validity checked (*RPY) 22 Reply, validity checked (*RPY) 23 Reply, message default used (*RPY) 24 Reply, system default used (*RPY) 25 Reply, from system reply list (*RPY) 162 Sending date: The date on which the message was sent. The date is specified in CYYMMDD format where Country, YY=year, MM=month, and DD=day. Sending job name: The name of the job that sent the message ID to the message queue. Sending job number: The job number associated with the job that sent the message ID to the message queue. Sending program name: The name of the program that sent the message or the name of the ILE program that contains the procedure that sent the message. When the name of the program is known, the 10-character program name is returned left- justified in the field and the final two characters contain blanks. In certain conditions when the name of the program that sent the message is not known, this field contains the 6-byte hexadecimal address of the program converted into 12 displayable characters. Sending time: The time at which the message was sent. The time is specified in HHMMSS format where HH=hours MM=minutes and SS=seconds. Sending user profile: The user profile used to submit the job that sent the message ID to the message queue. Severity: The severity of the received message. Possible values range from 0 to 99. Monitor program examples 163 Monitor program examples The following is an example of how various programs called by one monitor interact. Three example programs illustrate the operation of a message queue monitor. The message queue monitor is set up to monitor the QSYSOPR message queue for message ID CPI591A (Controller varied off or not recognized by local system). An interface exit program verifies that the line is active before starting the monitor. When the monitor receives message ID CPI591A, the condition program verifies that the line is active. The event program attempts to vary on the controller. Note: The examples in this section are provided on an as is basis. Interface exit program example This interface exit program is used by a message queue monitor that monitors the QSECOFR message queue for message ID CPI591A (Controller varied off or not recognized by local system). This exit program is called before and after an option is 164 taken on the monitor and every time an option is taken. This program only takes action on a pre-processing call for the option to start the monitor (option 9). Condition program example This condition program is used by a message queue monitor that monitors the QSYSOPR message queue for message ID CPI591A (Controller varied off or not recognized by local system). When this message arrives on the QSYSOPR message queue, this condition program is called to verify that the line is active. If the line is active the event program is called. Otherwise, the condition program tells the monitor Table 22. Interface exit program example PGM PARM( &MONI TOR &EVTCLS &CMDOPT &PREPOST &RTNCOD &EXCPTI D) / *********************************************************************/ / * Par amet er s */ / *********************************************************************/ DCL &MONI TOR *CHAR 10 / * Moni t or name */ DCL &EVTCLS *CHAR 10 / * Event cl ass */ DCL &CMDOPT *CHAR 4 / * Char act er r epr esent at i on of opt i on */ DCL &PREPOST *CHAR 1 / * Pr e or post opt i on cal l - 0=pr e, 1=post */ DCL &RTNCOD *CHAR 1 / * Ret ur n code - 0=cont i nue wi t h opt i on */ / * 1=do not cont i nue wi t h */ / * opt i on */ DCL &EXCPTI D *CHAR 7 / * Except i on I D f or hi st or y l og */ / *********************************************************************/ / * Local var i abl es */ / *********************************************************************/ DCL &STATUS *DEC LEN( 5 0) CHGVAR &RTNCOD VALUE( ' 0' ) / * ' 0' =Cont i nue wi t h r equest */ / *********************************************************************/ / * I f t hi s i s a pr e- pr ocessi ng cal l f or t he st ar t opt i on t hen ver i f y */ / * t hat t he l i ne i s ACTI VE. I f i t i sn' t t hen don' t st ar t t he */ / * moni t or . */ / *********************************************************************/ I F ( ( &PREPOST *EQ ' 0' ) *AND ( &CMDOPT *EQ ' 0900' ) ) THEN( DO) RTVCFGSTS CFGD( TRNLI NE) CFGTYPE( *LI N) STSCDE( &STATUS) I F ( &STATUS *EQ 60) THEN( DO) CHGVAR &RTNCOD VALUE( ' 1' ) / * Do not st ar t moni t or */ CHGVAR &EXCPTI D VALUE( ' MSG0001' ) ENDDO ENDDO Monitor program examples 165 to continue. Refer to “Additional data structures” on page 156 for information about the DTLINFO parameter. Event program example A message queue monitor that monitors the QSECOFR message queue for message ID CPI591A uses this event program. This event program is called if the message arrives and the line is active. The event program attempts to vary on the controller for Table 23. Condition program example PGM PARM( &MONI TOR &EVTCLS &DTLI NFO &RTNCOD) / *********************************************************************/ / * Par amet er s */ / *********************************************************************/ DCL &MONI TOR *CHAR 10 / * Moni t or name */ DCL &EVTCLS *CHAR 10 / * Event cl ass */ DCL &DTLI NFO *CHAR 752 / * Det ai l i nf or mat i on based on event cl ass */ DCL &RTNCOD *CHAR 1 / * Ret ur n code - 0=cal l event pr ogr am */ / * 1=I f gr oup moni t or , pr ogr am*/ / * f ai l ed, moni t or st at us i s */ / * I NACTI VE. Ot her wi se, */ / * cont i nue t o moni t or , do */ / * not cal l event pr ogr am */ / *********************************************************************/ / * Local var i abl es */ / *********************************************************************/ DCL &MSGI D *CHAR 7 DCL &STATUS *DEC LEN( 5 0) / * Set t he r et ur n code t o 1 t o def aul t t o not cal l t he event pr ogr am*/ CHGVAR &RTNCOD VALUE( ' 1' ) / * I f t he event cl ass i s *MSGQ t hen get t he message I D t hat caused */ / * t he condi t i on pr ogr amt o be cal l ed f r omt he det ai l i nf or mat i on. */ I F ( &EVTCLS *EQ ' *MSGQ ' ) THEN( DO) CHGVAR &MSGI D VALUE( %SST( &DTLI NFO 21 7) ) / * I f t he message I D i s CPI 591A t hen ver i f y t hat t he l i ne i s */ / * act i ve ( STATUS = 60) . I f i t i s act i ve t hen cal l t he event pgm. */ I F ( &MSGI D *EQ ' CPI 591A' ) THEN( DO) RTVCFGSTS CFGD( TRNLI NE) CFGTYPE( *LI N) STSCDE( &STATUS) I F ( &STATUS *EQ 60) THEN( + CHGVAR &RTNCOD VALUE( ' 0' ) ) ENDDO ENDDO ENDPGM 166 the line indicated in the message ID. Refer to “Additional data structures” on page 156 for information about the DTLINFO parameter. Table 24. Event program example PGM PARM( &MONI TOR &EVTCLS &DTLI NFO &RTNCOD &EXCPTI D) / *********************************************************************/ / * Par amet er s */ / *********************************************************************/ DCL &MONI TOR *CHAR 10 / * Moni t or name */ DCL &EVTCLS *CHAR 10 / * Event cl ass */ DCL &DTLI NFO *CHAR 752 / * Det ai l i nf or mat i on based on event cl ass */ DCL &RTNCOD *CHAR 1 / * Ret ur n code - 0=moni t or st at us ACTI VE or */ / * gr oup moni t or I NACTI VE */ / * 1=moni t or st at us FAI LED/ ACT */ / * or gr oup moni t or FAI LED */ / * 2=moni t or st at us FAI LED */ DCL &EXCPTI D *CHAR 7 / * Except i on I D f or hi st or y l og */ / *********************************************************************/ / * Local var i abl es */ / *********************************************************************/ DCL &MSGI D *CHAR 7 / * Get t he message I D whi ch i s i n t he 21- 27t h posi t i ons of t he det ai l */ / * i nf or mat i on. */ CHGVAR VAR( &MSGI D) VALUE( %SST( &DTLI NFO 21 7) ) / * I f t he message I D i s CPI 591A t hen at t empt t o Var y on t he cont r ol l er . */ I F COND( &MSGI D *EQ ' CPI 591A' ) THEN( + VRYCFG CFGOBJ ( CONTROLLER) CFGTYPE( *CTL) STATUS( *ON) ) / * Set r et ur n code t o ' 0' t o t el l t he message queue moni t or t o r emai n */ / * act i ve*/ CHGVAR &RTNCOD VALUE( ' 0' ) / * Set t he except i on I D t o bl anks si nce t he r et ur n code i s ' 0' */ CHGVAR &EXCPTI D VALUE( ' ' ) ENDPGM 167 CHAPTER 9 Resolving problems This section identifies how to handle problems with MIMIX Monitor. 168 Gathering information before reporting a problem Before you report a problem, you should gather the following information: • The MIMIX product, library, installed version, and IBM i operating system level on the system you are using. To determine this information, follow the procedure “Obtaining MIMIX and IBM i information from your system” on page 168. • The Message ID number for any error messages associated with the problem. If you receive error messages, record the message number, any replacement text (such as “Process X failed for file Y”), and the to and from program information, if available. Since many messages have similar text, this information is much more helpful to us and enables us to handle your call more efficiently. • The specific operation you were attempting to perform when the error condition occurred. It is important that we understand what you were trying to do when you encountered the problem. Try to write down the specific sequence of events that you were doing when the error condition occurred, such as the commands entered, the display you were working from, or the program that was running. Obtaining MIMIX and IBM i information from your system To obtain the necessary MIMIX and IBM i information before reporting a problem, do the following: 1. Do one of the following to access the Lakeview Technology Installed Products display: • If you are configured for a MIMIX replication environment, select option 31 (Product management menu). Then select option 2 (Work with products). • From a command line, enter LAKEVIEW/WRKPRD 2. Next to the product you want, type a 6 (About version) and press Enter. The About pop-up appears, showing the Product, Library, Installed version, and the OS/400 level on this system. 3. Press F9 (Fixes) to see the Work with Installed Fixes display. From this display you can determine the latest level of the MIMIX cumulative fix package that is installed. Note: You should know the version and release level (VnRnMn) of the IBM i operating system that is on each system with which you are working. Use the process above on each system. MIMIX Monitor commands by group 169 APPENDIX A MIMIX Monitor commands This section identifies MIMIX Monitor commands, grouped by the area or function in the product for which they are used. Security authorization levels for MIMIX Monitor commands are not included. The Using License Manager book identifies the minimum authorization levels for commands and describes how to change them. MIMIX Monitor commands by group MIMIX Monitor includes commands for starting and ending the master monitor, for working with monitor objects, switch definitions, and switch device entries, as well as commands specialized for the UPS monitor. You should also be familiar with the MIMIX commands that apply to transfer definitions and system definitions Master monitor commands The following commands are used to start and end the master monitor which MIMIX Monitor uses to control all other monitors. Monitor commands Only required parameters of the following commands are listed. For more information about optional parameters and descriptions of all parameters, prompt on the command then use F1 (Help). Commands for the UPS monitor are listed separately. Name Command End Master Monitor ENDMSTMON Start Master Monitor STRMSTMON There are no parameters for these commands. Name Command Required parameters Add Monitor Information ADDMONINF 1 MONITOR, CMD Change Monitor Information 1 CHGMONINF 1 MONITOR Change Monitor Object CHGMONOBJ MONITOR Change Monitor Status CHGMONSTS MONITOR Copy Monitor Object CPYMONOBJ FROMMON, TOMON Create Monitor Object CRTMONOBJ MONITOR, EVTCLS Delete Monitor Object DLTMONOBJ MONITOR Display Monitor Information DSPMONINF MONITOR Display Monitor Object DSPMONOBJ MONITOR Display Monitor Status DSPMONSTS MONITOR End Monitor ENDMON MONITOR Export Monitor Object EXPMONOBJ MONITOR Hold Monitor HLDMON MONITOR Import Monitor Object IMPMONOBJ FROMMON MIMIX Monitor commands 170 Switch definition commands Only required parameters of the following commands are listed. For more information about optional parameters and descriptions of all parameters, prompt on the command then use F1(Help). Switch device entry commands Only required parameters of the following commands are listed. For more information about optional parameters and descriptions of all parameters, prompt on the command then use F1 (Help). MIMIX Model Switch Framework commands The MIMIX Model Switch Framework is designed to aid you in implementing a switching environment. Only required parameters of the following commands are listed. For more information about optional parameters and descriptions of all parameters, prompt on the command then use F1 (Help). Release Monitor RLSMON MONITOR Rename Monitor Object RNMMONOBJ FROMMON, TOMON Run Monitor RUNMON MONITOR Start Monitor STRMON MONITOR Work with Monitors WRKMON Work with Monitor Information WRKMONINF MONITOR 1 This command can only be accessed from the associated CHGMONOBJ command. Name Command Required parameters Name Command Required parameters Change Switch Definition CHGSWTDFN SWITCH Create Switch Definition CRTSWTDFN SWITCH Delete Switch Definition DLTSWTDFN SWITCH Display Switch Definition DSPSWTDFN SWITCH Display Switch Status DSPSWTSTS SWITCH End Switch ENDSWT SWITCH End Switch Screen ENDSWTSCN SWITCH Set Switch Source SETSWTSRC SWITCH, DTASRC Start Switch STRSWT SWITCH Start Switch Screen STRSWTSCN SWITCH Work with Switch Definitions WRKSWT Name Command Required parameters Add Switch Device Entry ADDSWTDEVE SWITCH, DEV Change Switch Device Entry CHGSWTDEVE SWITCH, DEV Display Switch Device Entry DSPSWTDEVE SWITCH, DEV Load Switch Device Entries LODSWTDEVE SWITCH Remove Switch Device Entry RMVSWTDEVE SWITCH, DEV Work with Switch Device Entries WRKSWTDEVE SWITCH Name Command Required parameters Change Switch Framework CHGSWTFWK SWTFWK Check Switch Framework CHKSWTFWK SWTFWK, MIMIX Monitor commands by group 171 UPS monitor commands Many of the UPS monitor commands have optional parameters. To see the optional parameters and their descriptions, prompt on the command then press F1 (Help). Create Switch Framework CRTSWTFWK SWTFWK, PRDSYSDFN, EXITPGMLIB Delete Switch Framework DLTSWTFWK SWTFWK Retrieve Switch Framework RTVSWTFWK SWTFWK Run Switch Framework RUNSWTFWK SWTFWK Name Command Required parameters Name Command Required parameters Change UPS Availability CHGUPSAVL Change UPS Configuration CHGUPSCFG Change UPS Messages CHGUPSMSG MSGTYP Display UPS Monitor Status DSPUPSSTS Test Power Change TSTPWRCHG Update UPS Availability UPDUPSAVL Hardware switching devices 172 APPENDIX B Hardware switching devices If you choose to use a hardware switching device with MIMIX Monitor, this section describes how to plan for and install hardware switching equipment. This section describes the Pro Switching System 2 (SM900A) device that can be used with MIMIX Monitor to handle your hardware switching requirements. The SM900A is manufactured by Black Box Corporation. Note: The SM517A Remote Gang Controller will continue to be supported by MIMIX Monitor but is no longer available from Black Box Corporation. Using the Pro Switching System 2 (SM900A) for your hardware switch requirements is recommended. Hardware switch configurations 173 Hardware switch configurations You have many options when designing hardware switching configuration to meet your availability management needs. This information describes two common configuration possibilities. When planning a hardware switching configuration, consider the distance the switching hardware will be from the backup system. Local configuration - SM900A switch You must ensure that this switch device is configured so the master chassis address is set to rAc (displayed on the upper display) and 00 (in the lower display). When the backup system and the switching hardware are located near each other (150-200 feet or less), you can connect them using a communication cable. Figure 10. Hardware switching—local configuration. A standard communications cable is used between the backup system and the remote system gang controller. Pro Switching System 2 (SM900A) A B Backup iSeries IBM Communications Cable (up to 150 feet) EIA-J 32/V.24 EIA-J 32/V.24 Enhanced EIA-449/V.36 Modified Modem Eliminator (CBCA229179) 174 Remote configuration When the distance between the backup system and the switching hardware exceeds 150-200 feet, the connection between them requires a dial-up communication line and modems. Figure 11. Hardware switching—remote configuration (SM900A) Switching hardware requirements You should consult the product documentation provided with the hardware switching equipment for various hardware requirements. A rack card is required to interface each set of ports (A-side/B-side) that can be switched. Rack cards can interface and switch digital, analog, or coaxial media. Each rack card contains at least three connectors: one device-in connector and two device- out connectors. The device-in (common) connector connects the user device to the card. One device-out connector connects the rack card to the production system and the remaining device-out connectors connect the rack card to the backup system. Figure 12 shows examples of rack card connectors. Figure 12. Example rack card connections. Pro Switching System 2 (SM900A) A B Backup iSeries IBM Communications Cable (up to 150 feet) EIA-J 32/V.24 EIA-J 32/V.24 Enhanced EIA-449/V.36 Modem Modem OUT to Production AS/400 OUT to Backup AS/400 OUT to Production AS/400 OUT to Backup AS/400 OUT to Production AS/400 OUT to Backup AS/400 Device IN Device IN Device IN Example 1 Example 2 Example 3 Hardware switch configurations 175 Some cards, such as twinaxial interface cards, require two card slots. You can mix the types of rack cards within each automatic rack chassis. Empty card slots may be filled with blank panels. The following types of rack cards are typically available: Modified modem eliminator: In a local configuration, the backup system is inserted between the remote system gang switch controller and the communications cable from the backup system. You need one modified modem eliminator for each remote system gang controller that is locally connected. For a local configuration, you will need a special modem eliminator adapter. This part (C1CB10590) is available from Black Box Corporation. This adapter provides a unique connector with the pinning shown in Figure 13. Figure 13. Pin-outs for cable to modified modem eliminator - SM900A. Modems and communication cables: In a remote configuration, two modems and communications cables provide the connection between the remote system gang controller and the backup system. On each side of the connection, you need a Table 25. Rack cards DB9 RJ 11 V.35 DB15 RJ 45 Wang BNC/TNC Double Coax RS-232 4-Wire utility Coax BNC Twinaxial 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 Control Module (SM903C RS-232) iSeries RS-232 176 modem and a communication cable no longer than 150 feet. Both modems must be set to run at the same speed as the remote system gang controller and must share the same communication characteristics. The modem speed for the SM900A is 9600 bps. IBM communications cables: You need one cable for each system. (This cable comes with the IBM Power TM Systems Communication Card.) These cables are used to connect the Power TM Systems to the remote system gang controller through either a local configuration or a remote configuration. Planning for switching hardware 177 Planning for switching hardware When you plan to use switching hardware with MIMIX Monitor, you need to identify the production and backup systems, the devices to be switched, and the number of ports and switching interfaces required. You also need to identify what devices and ports are being connected through the switching hardware and determine the types and lengths of cables the cables you need. You may find it helpful to make a sketch of your configuration, similar to Figure 14. Use Appendix C, “Work sheets for switching hardware, to help you determine your device and port assignments and your switching interface card and cable requirements. You will need information from these work sheets when you configure the switching hardware. Figure 14. Sample planning sketch. Workstation 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 Switching Hardware Printer Production AS/400 Backup AS/400 Workstation Controller Workstation Controller Streaming Tape Drive Port Port 0 4 4 7 2 6 Printer Tape Drive Workstation 178 Consider the following: Determine what hardware needs to be switched to the backup system. The hardware devices to be moved to the backup system in the event of a switch need to be switch- controlled. Note: Designating multiple points of failure provides the best system protection. To achieve this goal, the production system and the backup system should have at least two separate communications connections so that a single failure does not provoke an unnecessary device switch. MIMIX Monitor allows for either manual or automatic switching. Determine which best meets the needs of your enterprise. You must prepare the backup system for use as the production system. The backup system must be ready to support any applications, devices, user profiles, or other operations that you switch to it. Consider the location and designation of production and backup systems. Designating the production side as “ A” and the backup side as “ B” when connecting switching hardware is suggested. Determine whether the communication configuration between the backup system and the switching hardware is local or remote. Refer to “Hardware switch configurations” on page 173. This will affect your hardware and communications requirements. Determine the switching interface requirements (cables and rack cards) for production user devices. Use Work Sheet A: Rack Cards and Cables to assist you. When communicating over phone lines, keep in mind that anyone can intentionally or unintentionally call into your modems. Plan to make use of any security capabilities provided in your switching or communications hardware. Identify information you need for creating the switch event program and for configuring the switch definition and associated monitor objects. Consider the following: • Keep in mind that the commands required to enable the backup system to be used in production mode will be the basis for the switch (event) user exit program. • Identify the communication objects to be monitored by user-defined monitors and identify which user-defined monitors will participate in a group monitor designated to a switch definition. • Identify any objects to be associated with the user programs called by the monitors. • How many times should MIMIX Monitor retry or attempt recovery for each monitor object. Physical planning: The physical location of the production and backup systems and the switching hardware is flexible. Modems, modem eliminators, and workstation controllers can accommodate communication between the devices. You should consider the following: • Draw a floor plan that is to scale. This will help you determine locations of devices and racks, identify the types of cables you need, and ensure that cable lengths will be adequate. Planning for switching hardware 179 • Determine how to mount the switching hardware and where it will be placed. Switching hardware can be mounted on a table or in a data rack, a 19-inch rack, or a 19-inch cabinet. Rack mounting is considered most secure. • Consider the physical security of the location in which you place the switching hardware. Because switching between production and backup systems involves more than merely making a physical switch between “ A” and “ B” ports at the switch bank, it is important to place the switching hardware in a secure location to prevent unauthorized users from attempting to improperly perform a manual switch. • Before ordering hardware, review all environmental and electrical requirements for the location to ensure that cables you specify on your order will meet your requirements. Once the switching hardware and MIMIX Monitor are installed, keep in mind that whenever devices are added, removed, or relocated, it may be necessary to modify associated hardware and software configurations. At that time, be sure to update the planning documentation accordingly. 180 Related communications procedures These procedures describe how to set up communications that you will need to connect the backup system to the remote gang switch controller. You will need a dedicated communications resource. You will also need a separate communications resource for each hardware switch. Defining local communications Do the following to define communications for a local configuration: 1. Determine the resource name for the switch hardware communications. Record this information. 2. Create the communication line to the remote system gang controller using the command: CRTLI NASC LI ND(line-name) RSRCNAME(resource-name) LI NESPEED(line-speed) MAXBUFFER(2000) Where the following are defined as: line-name Communications line name. resource-name Resource name you recorded during the remote system gang controller installation. line-speed Line speed you recorded during the remote system gang controller installation. This is configured on the SM900A controller card. 3. Create the communications controller using the command: CRTCTLASC CTLD(controller-name) LI NKTYPE( *ASYNC) LI NE(line- name) Where the following are defined as: controller-name Controller name line-name Line name from CRTLINASC command 4. Create the device using the command: CRTDEVASC DEVD(device-name) RMTLOCNAME(remote-location-name) CTL(controller-name) Where the following are defined as: device-name Device name remote-location-name Remote location name controller-name Controller name specified in CRTCTLASC command Note: The device name and the remote location name are required when creating the switch definition. 5. Vary-on the line and verify that the line stays active. Related communications procedures 181 Defining remote communications Use either procedure to define communications for a remote configuration. For autodial V.25BIS modems Do the following to define communications for a remote configuration that uses autodial V.25BIS modems: 1. Determine the resource name for switch hardware communications. Record this information. 2. Create the communication line to the remote system gang controller using the command CRTLI NASC LI ND(line-name) RSRCNAME(resource-name) CNN( *SWTPP) MODEM( *NORMAL) MODEMRATE( *FULL) SWTCNN( *DI AL) DI ALCMD( *V25BI S) LI NESPEED(nnnn) MAXBUFFER(2000) Where the following are defined as: line-name Communications line name resource-name Resource name you recorded during the remote system gang controller installation nnnn Line speed you recorded during the remote system gang controller installation. This is configured on the SM900A controller card. Note: The line speed must match the speed of the remote system gang controller and the modems for remote configurations. 3. Create the communications controller using the command: CRTCTLASC CTLD( controller-name) LI NKTYPE( *ASYNC) SWI TCHED( *YES) LI NE( line-name) I NLCNN( *DI AL) CNNNBR( call- number) Where the following are defined as: controller-name Controller name line-name Line name from CRTLINASC command call-number Connection number to dial to connect to the modem. 4. Create the device using the command: CRTDEVASC DEVD(device-name) RMTLOCNAME(remote-location-name) CTL(controller-name) Where the following are defined as: device-name Device name remote-location-name Remote location name controller-name Controller name specified in CRTCTLASC command Note: The device name and the remote location name are required when creating the switch definition. 182 5. Vary-on the line and verify that the line stays active. For other (non-autodial) modems This procedure creates a line that will not autodial when opened. Use an actual calling string as the call number when creating the switch definition. 1. Determine the resource name for switch hardware communications. Record this information. 2. Create the communication line to the remote system gang controller using the command: CRTLI NASC LI ND(line-name) RSRCNAME(resource-name) CNN( *SWTPP) SWTCNN( *DI AL) LI NESPEED(nnnn) CALLNBR(call- number) AUTODI AL( *YES) I NACTTMR( *NOMAX) MAXBUFFER(2000) Where the following are defined as: line-name Communications line name, (SWITCHLIN1) resource-name Resource name you recorded during the remote system gang controller installation nnnn Line speed you recorded during installation of the remote system gang controller. This is configured on the SM900A controller card. call-number Phone number of modem, will not autodial when opened. Note: The line speed must match the speed of the remote system gang controller hardware and the modems used for remote configurations. 3. Create the communications controller using the command CRTCTLASC CTLD(controller-name) LI NKTYPE( *ASYNC) SWI TCHED( *YES) SWTLI NLST(line-name) CNNNBR(call-number) SWTDSC( *YES) Where the following are defined as: controller-name Controller name line-name Line name from CRTLINASC command call-number Connection number to dial to connect to the modem. 4. Create the device using the command: CRTDEVASC DEVD(device-name) RMTLOCNAME(remote-location-name) CTL(controller-name) Where the following are defined as: device-name Device name remote-location-name Remote location name controller-name Controller name specified in CRTCTLASC command Note: The device name and the remote location name are required when creating the switch definition. Related communications procedures 183 5. Vary-on the line and verify that the line stays active. Work sheets for switching hardware 184 APPENDIX C Work sheets for switching hardware This section provides work sheets that you can use when you are configuring commercially available hardware switching devices for use with MIMIX Monitor. Use the work sheets in this appendix to help you configure the hardware switching device. Work sheet A: rack cards and cables Use the following work sheet to identify the cables to connect to each card in a rack chassis. Use one work sheet for each automatic rack chassis. Table 26. Rack cards and cables work sheet Slot assignments for rack chassis #___________ Slot Card code Production cable Backup cable Device cable 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Work sheet B: device and port assignments 185 Work sheet B: device and port assignments Work sheet C: port layout Table 27. Device and port assignment work sheet Device and port assignments Production system serial #______________________________ Backup system serial #_________________________________ Device Description Production WSC port Backup WSC port Table 28. Port layout work sheet WSC name and port Card type slot number Device name Work sheets for switching hardware 186 0 1 2 3 4 5 6 Production Backup Production Backup Production Backup Production Backup Production Backup Production Backup Table 28. Port layout work sheet Supported upgrade paths for copying configuration data 187 APPENDIX D Copying configuration data This section describes how to use the Copy Configuration Data (CPYCFGDTA) command to copy monitor configuration data. The CPYCFGDTA command copies configuration data from one library to another library on the same system. Use this information after MIMIX Enterprise or MIMIX Professional is installed. Supported upgrade paths for copying configuration data The supported scenarios are as follows: Checklist: copy monitor configuration data from a previ- ous release Use this checklist after you have installed version 7 MIMIX Enterprise or MIMIX Professional and want to copy configuration data from an earlier release of MIMIX Monitor: 1. Verify that there are valid system and transfer definitions in the product installation library. 2. Use the procedure in “Using the CPYCFGDTA command for MIMIX Monitor” on page 187 to copy the configuration information to the new library. 3. Use the WRKMON command in the new installation library to verify that all of the previous monitor objects have been created in the new library. Using the CPYCFGDTA command for MIMIX Monitor You can use the Copy Configuration Data (CPYCFGDTA) command to copy existing configuration data to a new installation of MIMIX. Note: By default, the CPYCFGDTA command replaces all MIMIX configuration data in the current product library with the information from the specified Table 29. Supported scenarios for copying configuration From To MIMIX version 7 MIMIX version 7 a a. The installation you are copying to must be at the same or a higher level service pack. MIMIX version 6 MIMIX version 7 Copying configuration data 188 library. Any configuration created in the product library will be replaced with data from the specified library. This may not be desirable. To copy the appropriate configuration data, do the following: 1. The current (version 7) product that will receive the copied configuration data must be shut down for the duration of this procedure. See topic “Choices when ending replication” in the MIMIX Operations book. 2. Sign on to the system with the security officer (QSECOFR) user profile or with a user profile that has security officer class authority and all special authorities. 3. From the command line on the MIMIX Basic Main Menu for the version 7 installation, type the command CPYCFGDTA and press F4 (Prompt). 4. At the Copy from library prompt, specify the name of the MIMIX installation library from which you want to copy data. 5. Press Enter. Notices ©Copyright 1999, 2010, Vision Solutions, Inc. All rights reserved. The information in this document is subject to change without notice and is furnished under a license agreement. This document is proprietary to Vision Solutions, Inc., and may be used only as authorized in our license agreement. No portion of this manual may be copied or otherwise reproduced, translated, or transmitted in whole or part, without the express consent of Vision Solutions, Inc. If you are an entity of the U.S. government, you agree that this documentation and the program(s) referred to in this document are Commercial Computer Software, as defined in the Federal Acquisition Regulations (FAR), and the DoD FAR Supplement, and are delivered with only those rights set forth within the license agreement for such documentation and program(s). Use, duplication or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 (48 CFR) or subparagraphs (c)(1) & (2) of the Commercial Computer Software - Restricted Rights clause at FAR 52.227-19. Vision Solutions, Inc. makes no warranty of any kind regarding this material and assumes no responsibility for any errors that may appear in this document. The program(s) referred to in this document are not specifically developed, or licensed, for use in any nuclear, aviation, mass transit, or medical application or in any other inherently dangerous applications, and any such use shall remove Vision Solutions, Inc. from liability. Vision Solutions, Inc. shall not be liable for any claims or damages arising from such use of the Program(s) for any such applications. Examples and Example Programs: This book contains examples of reports and data used in daily operation. To illustrate them as completely as possible the examples may include names of individuals, companies, brands, and products. All of these names are fictitious. Any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. This book contains small programs that are furnished by Vision Solutions, Inc. as simple examples to provide an illustration. These examples have not been thoroughly tested under all conditions. Vision Solutions, therefore, cannot guarantee or imply reliability, serviceability, or function of these example programs. All programs contained herein are provided to you “AS IS.” THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. ®MIMIX and Vision Solutions are registered trademarks of Vision Solutions, Inc. ™ IntelliStart, MIMIX dr1, MIMIX AutoGuard, MIMIX AutoNotify, MIMIX Availability Manager, MIMIX Enterprise, MIMIX Professional, MIMIX DB2 Replicator, MIMIX Object Replicator, MIMIX Monitor, MIMIX Promoter, MIMIX Switch Assistant, RJ Link, Replicate1, Vision AutoValidate, and MIMIX Global are trademarks of Vision Solutions, Inc. AS/400, DB2, eServer, i5/OS, IBM, iSeries, OS/400, Power, System i, and WebSphere are trademarks of International Business Machines Corporation. Internet Explorer, Microsoft, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Netscape is a registered trademark of AOL LLC. Mozilla and Firefox are trademarks of the Mozilla Foundation. UNIX is a registered trademark of The Open Group in the United States and other countries. J ava and all J ava-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners. Corporate Headquarters Vision Solutions, Inc. Irvine, California USA Tel: +1 (949) 253-6500 190 Index A accessing MIMIX Main Menu 34 active monitor status 50 adding device entries 96 additional data structures detail information format 156 error code structure 159 API, MIMIX Monitor User Access 152 asynchronous processing 22, 59, 73 interval master monitor 25 authority all object (*ALLOBJ ) 30 B battery available power, updating 138 estimating maximum time 127 C cables communication 176 IBM communications 176 calling commands from a monitor 58 cards, rack 174 changing logon message during switch 98 monitor object 51 monitor status 45 switch definition 85 switch device entry 96 checklist configuring UPS monitor 126 preparing a switch 31 preparing for MIMIX Monitor 29 commands, by mnemonic ADDMONINF 62 ADDMSGLOGE 145 ADDSWTDEVE 96 CHGMONINF 51 CHGMONOBJ 51 CHGMONSTS 45 CHGSWTDEVE 96 CHGSWTDFN 85 CHGSWTFWK 105 CHGUPSAVL 138 CHGUPSCFG 133 CHGUPSMSG 135 CHKSWTFWK 105 CPYCFGDTA 187 CRTMONOBJ 61 CRTSWTDFN 81 CRTSWTFWK 105 DLTMONOBJ 51 DLTSWTDFN 86 DLTSWTFWK 105 DSPMONOBJ 52 DSPMONSTS 50 DSPSWTDEVE 97 DSPSWTDFN 87 DSPSWTSTS 94 ENDMON 43 ENDSWT 89 ENDSWTSCN 98 EXPMONOBJ 53 HLDMON 47 IMPMONOBJ 54 LODSWTDEVE 96 MIMIX 34 RMVSWTDEVE 97 RNMMONOBJ 52 RSLMON 48 RTVSWTFWK 105 RUNMON 44 RUNSWTFWK 107 SETSWTSRC 91 STRMON 42 STRMSTMON 37 STRSWT 89 STRSWTSCN 98 TSTPWRCHG 139 UPDUPSAVL 138 WRKMON 39 WRKMONINF 52 WRKMSGLOG 49 WRKSWT 80 WRKSWTDEVE 96 commands, by name Add Message Log Entry 145 Add Monitor Information 62 Add Switch Device Entry 96 Change Monitor Information 51 Change Monitor Object 51 Change Monitor Status 45 Change Switch Definition 85 Change Switch Device Entry 96 Change Switch Framework 105 Change UPS Availability 138 Change UPS Configuration 133 191 Change UPS Messages 135 Check Switch Framework 105 Copy Configuration Data 187 Create Monitor Object 61 Create Switch Definition 81 Create Switch Framework 105 Delete Monitor Object 51 Delete Switch Definition 86 Delete Switch Framework 105 Display Monitor Object 52 Display Monitor Status 50 Display Switch Definition 87 Display Switch Device Entry 97 Display Switch Status 94 End Monitor 43 End Switch 89 End Switch Screen 98 Export Monitor Object 53 Hold Monitor 47 Import Monitor Object 54 Load Switch Device Entries 96 MIMIX 34 Release Monitor 48 Remove Switch Device Entry 97 Rename Monitor Object 52 Retrieve Switch Framework 105 Run Monitor 44 Run Switch Framework 107 Set Switch Source 91 Start Master Monitor 37 Start Monitor 42 Start Switch 89 Start Switch Screen 98 Test Power Change 139 Update UPS Availability 138 Work with Message Log 49 Work with Monitor Information 52 Work with Monitors 39 Work with Switch Definitions 80 Work with Switch Device Entries 96 commands, calling from a monitor 58 commands, list of master monitor 169 monitor 169 switch definition 170 switch device entry 170 UPS monitor 171 concepts 13 MIMIX Model Switch Framework 16 switching 14 condition program creating 149 example 164 parameters 149 conditions, predefined 13 configuration data, copying 187 contacting Vision Solutions 11 copy configuration data 187 CustomerCare 11 D deleting monitor object 51 switch definition 86 DGSELECT, user exit program 121 disabled monitor 25, 77 disabling, MIMIX Model Switch Framework 114 displaying job log for monitor jobs 55 monitor object 52 switch definition 87 switch device entry 97 displays list of monitors 39 displays, accessing Work with Switch Definitions 80 Work with Switch Device Entries 96 documents, MIMIX 8 E enabling, MIMIX Model Switch Framework 114 ending monitor 43 monitors for a switch 89 UPS monitor 136 ENDPROD, user exit program 121 estimating time maximum battery 127 power down options 127 event class description 13 subclass 72 event class types *EXDJ RN 75 *GROUP 77 *INTERVAL 72 *J RN 74 *MSGQ 75 *PREDFN 77 192 *TIME 76 event program creating 150 description 14 example 165 MSFEVENT 106 parameters 150 example group monitor 77 interval monitor 73 journal monitor 74 message queue monitor 76 time monitor 76 example program condition 164 event 165 interface exit 163 F field descriptions MMUSRACCS API 154 program interfaces 160 formats, MMUSRACCS API 153 G group monitor creating with CRTSWTFWK command 105 description 77 processing 25 when to use 77 H hardware switching configuring communications 180 planning 178 hardware switching devices local configurations, supported 173 planning 177 planning work sheets 184 remote configurations, supported 174 synchronizing hardware 92 held monitor releasing 48 holding a monitor 47 I impersonation, IP 31 switch definition for 81, 83 importing monitors 54 interface exit program calling when importing monitor 55 creating 147 description 14 example 163 operation 20 parameters 147 specifying in monitor object 58 interval master monitor description 25 ending 38 interaction with active interval monitors 25 starting indirectly 38 interval monitor asynchronous and synchronous processing 73 description 72 subclasses 72 when to use 73 J job log 56 job priority, for UPS monitor 131 journal monitor description 74 when to use 74 writing entry to journal 74 L local configuration, SM900A switch 173 M master monitor description 21 ending 37 starting 37 menu MIMIX Main 34 message log 145 message queue notifying of power below 100% 138 system operator 140 message queue monitor description 75 example programs for a 163 when to use 76 messages, MIMIX Model Switch Framework 115 MIMIX monitor 193 key capabilities 12 MIMIX Monitor, security considerations 30 MIMIXSBS subsystem 33 MIMIXUPS subsystem 126 MMUSRACCS member 152 modem 176 other 182 V.25BIS 181 modified modem eliminator 175 monitor creating 57 monitor definition, See monitor object 13 monitor group 57 monitor object 13 monitor types *EXDJ RN 75 *GROUP 77 *INTERVAL 72 *J RN 74 *MSGQ 75 *PREDFN 77 *TIME 76 monitors associated with switch definition 89 copying 51 creating 61 deleting 51 displaying 52 ending 43 exporting 53 extended journal 75 group 77 holding 47 importing 54 inactive status 50 interval 72 interval master monitor 25 job logs 55 journal 74 master monitor 21 message queue 75 printing 52 programming for 144 releasing 48 renaming 52 shipped with product 123 starting 42 status, displaying 50 time 76 tips for creating 57 user-defined 13 user-specified information 52 working with 36 monitors shipped with MIMIX 17 independent ASP threshold 17 MMNFYNEWE 17 remote journal link 17 N notifying users of switch 98 O operating requirements, MIMIX Model Switch Framework 103 operation asynchronous processing 23 interface exit processing 20 synchronous processing 22 operator intervention, requesting power down 134 orphaned data, objects 122 overview, MIMIX Monitor 12 P parameters condition program 149 exit program 150 interface exit program 147 MMUSRACCS API 152 planning, hardware switching work sheets 184 policies default switch framework 103 power simulating changes in 139 updating available power for UPS monitor 138 power down option changing 133 controlled 124 estimating time for 127 immediate 124 instant 125 power down, requesting operator intervention 134 predefined monitor, UPS monitor 124 preparation sequence, changing 133 printing monitor object 52 switch definition 88 194 switch device entry 97 problems reporting a problem 168 process type 59 program condition program example 164 condition program parameters 149 event program example 165 event program parameters 150 interface exit program example 163 interface exit program parameters 147 interface exit program, effect on monitors 14 running when monitor is inactive 44, 95 startup, modifying 129 UPS monitor failure exit program 125 UPS monitor restore exit program 125 programming MMUSRACCS API 152 switching operations 146 UPS monitor 146 publications IBM eServer iSeries 10 R removing a switch, device entry 97 renaming a monitor 52 retry attempts 22, 58 RUNSWTFWK, using 107 S security MIMIX Model Switch Framework 104 MIMIX Monitor considerations 30 shipped monitor UPSMON 17 simulating power changes 139 starting master monitor 37 MIMIXUPS subsystem 126 monitor 42 monitors for a switch definition 89 UPS monitor 136 startup program modifying 129 startup programs MIMIX subsystem 33 status changing monitor 45 inactive monitors 50 master monitor, active requirement 37 monitor status, displaying 50 monitor values 40, 50 monitor, disabled 25, 77 status codes, MIMIX Model Switch Framework 117 STRBCKUP, user exit program 121 STRPROD, user exit program 121 subclass 72 subsystem MIMIXSBS, starting 33 MIMIXUPS, starting 126 Switch Assistant 100 switch definition changing 85 checklist for creating 31 creating 81 creating type *NONE 83 deleting 86 description 15 displaying 87 displaying status 94 ending associated monitors 89 monitors associated with 89 printing 88 starting associated monitors 89 using IP impersonation 81 working with 79 switch framework process, stopping 121 switchback 101 switching after errors 116 automatically 106 command for 28 concepts 14 configuration 173 manually 91 switching devices, hardware 172 switchover 101 SWTFWKCFM, user exit program 121 synchronization 101 synchronizing switching hardware 92 synchronous processing 22, 59, 73 T testing switching operation 32 UPS configuration 137 UPS monitor 139 195 time monitor creating 61 description 76 tips 62 when to use 76 tips for all monitors 57 for time monitors 62 U updating available power 138 UPS monitor 123 accessing menu 132 battery time, estimating 127 configuration checklist 126 ending 136 ensuring always active 129 exit programs overview 125 failure exit program 133 job priority, setting 131 maximum UPS battery time 124 operator intervention overview 125 operator intervention, setting 134 overview 124 power down option 133 power down time, estimating 127 preparation functions overview 124 preparation sequence 133 preparation time 133 restore exit program 134 starting 136 subsystem, changing 143 testing configuration 137 updating available power 138 warning message text, changing 135 user exit programs DGSELECT 121 ENDBCKUP 121 ENDPROD 121 STRBCKUP 121 STRPROD 121 SWTFWKCFM 121 user profile requirements 44, 103 W when to use group monitor 77 interval monitor 73 journal monitor 74 message queue monitor 76 time monitor 76 work sheets 184