System Automation for z/OS: End-to-End Automation Adapter · The System Automation for Application Manager library The following table shows the information units in the System Automation

System Automation for z/OS

End-to-End Automation AdapterVersion 3 Release 5

SC34-2750-01

IBM

System Automation for z/OS

End-to-End Automation AdapterVersion 3 Release 5

SC34-2750-01

IBM

NoticesBefore using this information and the product it supports, read the general information under Appendix D, “Notices,” onpage 103.

Edition Notes

This edition applies to IBM Tivoli System Automation for z/OS Version 3, Release 5 (Program Number 5698-SA3),an IBM licensed program, and to all subsequent releases and modifications until otherwise indicated in neweditions or technical newsletters.

This edition replaces SC34-2750-00.

© Copyright IBM Corporation 2005, 2015.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . v

Tables . . . . . . . . . . . . . . . vii

How to send your comments to IBM . . ix

About this publication . . . . . . . . xiWho should use this publication . . . . . . . xiWhere to find more information . . . . . . . xi

The System Automation for Application Managerlibrary . . . . . . . . . . . . . . . xiThe System Automation for z/OS Library . . . xiRelated Product Information . . . . . . . xii

Accessibility . . . . . . . . . . . . . . xiiUsing assistive technologies . . . . . . . . xiiKeyboard navigation of the user interface . . . xii

Summary of Changes for SC34-2750-01 . . . . . xiiiNew Information . . . . . . . . . . . xiiiChanged Information . . . . . . . . . . xivDeleted Information . . . . . . . . . . xiv

Chapter 1. Introducing the end-to-endautomation adapter . . . . . . . . . . 1End-to-end automation management server . . . . 1The end-to-end automation adapter. . . . . . . 2

Purpose . . . . . . . . . . . . . . . 3Communication . . . . . . . . . . . . 3

Chapter 2. Quick Startup . . . . . . . 7Overview of Quick Startup . . . . . . . . . 7SA z/OS automation policy . . . . . . . . . 8SA z/OS initialization member INGXINIT . . . . 8SA z/OS sample JCL procedure INGXADPT . . . 8SA z/OS USS configuration files (automatically) . . 9SA z/OS USS configuration files (manually) . . . 10NetView SSI JCL procedure . . . . . . . . . 10NetView Event/Automation Service(E/AS) . . . . 11End-to-End Adapter startup . . . . . . . . . 11Verifying end-to-end automation adapter . . . . 12Following up . . . . . . . . . . . . . . 12

Chapter 3. Prerequisites anddependencies. . . . . . . . . . . . 13Setup Java Runtime . . . . . . . . . . . 13Setup Environment Variables . . . . . . . . 13Setup Install-Root and Custom-Root Directory. . . 14Default USS File System . . . . . . . . . . 14User-Defined USS File System . . . . . . . . 14Shared USS File System . . . . . . . . . . 16

Chapter 4. Enabling NetViewEvent/Automation Service (E/AS) . . . 17Starting the E/AS Address Space . . . . . . . 17

Customize the Sample Procedure . . . . . . . 17Configuring the global initialization file (Default:IHSAINIT) . . . . . . . . . . . . . . 18Configuring the NetView message adapter service(Default: IHSAMCFG) . . . . . . . . . . . 18

Chapter 5. Customizing SystemAutomation Agent . . . . . . . . . . 19SA z/OS initialization member INGXINIT . . . . 19SA z/OS automated operator functions . . . . . 19SA z/OS advanced automation options . . . . . 20

Chapter 6. Customizing the end-to-endautomation adapter . . . . . . . . . 23Configuration files . . . . . . . . . . . . 23

The automation adapter master configuration file 23The automation adapter plug-in configuration file 25The SSL configuration file . . . . . . . . 27How to Encrypt the Keystore Password . . . . 28How to Create Keystore and Truststore for Useby SSL . . . . . . . . . . . . . . . 29The JAAS configuration file . . . . . . . . 29The Java logger configuration file . . . . . . 30

Customizing USS . . . . . . . . . . . . 31Using the data directory for log files . . . . . 31Setting UNIX access privileges . . . . . . . 31Setting access privileges for TCP/IP connections 31

Customize the link list. . . . . . . . . . . 32

Chapter 7. Security . . . . . . . . . 33Authentication . . . . . . . . . . . . . 33Authority checking by the automation adapter . . 33

Authorization checking by user exit . . . . . 33Authorization checking by System Automationsecurity. . . . . . . . . . . . . . . 35

Chapter 8. Operating the end-to-endautomation adapter . . . . . . . . . 37How to use the automation adapter . . . . . . 37

USS script . . . . . . . . . . . . . . 37JCL Procedure using BPXBATCH . . . . . . 39SA z/OS defined resource . . . . . . . . 40

Chapter 9. Operating the end-to-endautomation adapter via SA z/OS . . . 41Automation purpose and rules . . . . . . . . 41

Non-disruptive recovery from errors . . . . . 41Resynchronization of the automation adapter . . 42Recycling the automation adapter in the samesystem . . . . . . . . . . . . . . . 42Restarting the automation adapter or failover to abackup system . . . . . . . . . . . . 42Automated applications . . . . . . . . . 43Grouping considerations . . . . . . . . . 43

© Copyright IBM Corp. 2005, 2015 iii

||||||||||||||||||||||||

||||||||||||

|||||

||||||||

|||||||||

||

Defining automation policy . . . . . . . . . 44Application definition for the NetViewevent/automation service (E2E_EAS) . . . . . 45Application definition for the end-to-endautomation adapter (E2E_ADPT) . . . . . . 46MOVE group for the automation adapters(E2E_ADPT_X) . . . . . . . . . . . . 53

Limitations to the automation . . . . . . . . 54

Chapter 10. Problem determination . . 55Diagnosis of the SA z/OS tasks for the adapter . . 55End-to-end automation adapter diagnosiscommands. . . . . . . . . . . . . . . 55Problems with selecting the primary agent . . . . 56Problems with the program-to-program interface . . 56Problems with NetView event/automation service 56

Examples . . . . . . . . . . . . . . 57Problems with consumer registration . . . . . . 57Link list errors . . . . . . . . . . . . . 58TCP/IP bind socket problem . . . . . . . . 58Timeout problems . . . . . . . . . . . . 59USS problems . . . . . . . . . . . . . 59USS Shared File System . . . . . . . . . . 60CHECK_HEALTH function failure. . . . . . . 60Automation domain remaining offline after errorrecovery . . . . . . . . . . . . . . . 60

Appendix A. Configuration fileparameters . . . . . . . . . . . . . 61

Appendix B. SA z/OS specificimplementation of the end-to-endautomation resource data model . . . 65Resource data displayed by the WebUI . . . . . 65

Domain object . . . . . . . . . . . . 65

Node object . . . . . . . . . . . . . 67Resource object . . . . . . . . . . . . 67

Requests issued by the operations console and theend-to-end automation manager . . . . . . . 69

Overwriting commands . . . . . . . . . 71Request priority . . . . . . . . . . . . 71Disregarding the hold flag . . . . . . . . 72

INGE2E . . . . . . . . . . . . . . . 72Example verification output . . . . . . . . 75

Status mapping . . . . . . . . . . . . . 76Introduction . . . . . . . . . . . . . 76Status mapping steps . . . . . . . . . . 76

Appendix C. Messages . . . . . . . . 81End-to-end automation adapter messages . . . . 81End-to-end automation adapter plug-in messages . 89

Appendix D. Notices . . . . . . . . 103Trademarks . . . . . . . . . . . . . . 105Terms and conditions for product documentation 105

Index . . . . . . . . . . . . . . . 107

iv System Automation for z/OS: End-to-End Automation Adapter

||||

||||

||

Figures

1. Parts of the end-to-end automationmanagement component . . . . . . . . 2

2. INGAMS output . . . . . . . . . . . 33. End-to-end automation adapter communication 44. End-to-end automation adapter communication 85. Sample environment variables,

ingadapter.properties . . . . . . . . . 156. Sample automation adapter master

configuration file, ing.adapter.properties . . . 247. TCP/IP port relationship for the end-to-end

automation components . . . . . . . . 258. Example automation adapter plug-in

configuration file, ing.adapter.plugin.properties 26

9. Example SSL configuration file,ing.adapter.ssl.properties . . . . . . . . 28

10. Sample JAAS configuration file,ing.adapter.jaas.properties . . . . . . . . 30

11. Sysplex group relationships . . . . . . . 4412. DISPAOPS command response . . . . . . 5513. INGAMS command dialog panel . . . . . 5614. Event/automation service STATUS information 5715. Event/automation service QSTATS information 5716. INGEVOBS LIST command response . . . . 58

© Copyright IBM Corp. 2005, 2015 v

||||||||||||||||||

vi System Automation for z/OS: End-to-End Automation Adapter

Tables

1. End-to-end automation library . . . . . . xi2. System Automation for z/OS Library . . . . xi3. Automation adapter advanced automation

options . . . . . . . . . . . . . . 204. Information Messages for AUDITMSG=true

parameter . . . . . . . . . . . . . 275. Master configuration file

(ing.adapter.properties) parameters. . . . . 616. Plug-in configuration file

(ing.adapter.plugin.properties) parameters . . 63

7. SSL configuration file(ing.adapter.ssl.properties) parameters . . . 64

8. Mapping of end-to-end automation requests toSA z/OS commands . . . . . . . . . 69

9. SA z/OS automation manager status mapping 7710. Status mapping: second step if the SA z/OS

compound status reports a problem . . . . 78

© Copyright IBM Corp. 2005, 2015 vii

|||

viii System Automation for z/OS: End-to-End Automation Adapter

How to send your comments to IBM

We appreciate your input on this publication. Feel free to send us any commentsyou might have.

If you have feedback to the manuals

If you have comments on the manuals, like clarity, accuracy, and completeness ofthe information, use the Feedback channel on IBM Knowledge Center to send yourcomments.1. Click Feedback > Email IBM Knowledge Center support at the bottom of IBM

Knowledge Center.2. Log in to the invoked mailbox; or if the Launch Application window is

displayed, choose one mailbox and log in. A new email is displayed after login.3. In the email body, write down your feedback. Please include the specific book

and topic name that you're commenting on.4. Send the email to the default recipient.5. SA z/OS team will respond to you by email as soon as possible.

If you have a technical problem

Use one of the following feedback methods:v Contact your IBM service representativev Call IBM technical supportv Visit the IBM zSeries support web page at www.ibm.com/systems/z/support/

When you send comments to IBM, you grant IBM a nonexclusive right to use ordistribute your comments in any way it believes appropriate without incurring anyobligation to you.

IBM or any other organizations will only use the personal information that yousupply to contact you about the issues that you submit.

© Copyright IBM Corp. 2005, 2015 ix

http://www.ibm.com/support/knowledgecenter/SSWRCJ_3.5.0/com.ibm.safos.doc_3.5/kc_welcome-444.html

http://www.ibm.com/support/knowledgecenter/SSWRCJ_3.5.0/com.ibm.safos.doc_3.5/kc_welcome-444.html

http://www.ibm.com/systems/z/support/

x System Automation for z/OS: End-to-End Automation Adapter

About this publication

This publication describes the IBM® Tivoli® System Automation for z/OS®

end-to-end automation adapter (also called the automation adapter). Theautomation adapter enables SA z/OS to take advantage of the end-to-endautomation that is provided by the IBM Tivoli System Automation for ApplicationManager. End-to-end automation provides continuous availability forheterogeneous distributed IT business applications and reduces the total cost ofownership.

Who should use this publicationThis publication is intended for:v System programmers—primarily responsible for the installation, configuration,

and customization of the automation adapter, but might also make use of thecommand interface

v Operators

Where to find more information

The System Automation for Application Manager libraryThe following table shows the information units in the System Automation forApplication Manager library:

Table 1. End-to-end automation library

Title Order Number

IBM Tivoli System Automation for Application Manager Installation andConfiguration Guide

SC33-2702

IBM Tivoli System Automation for Application Manager Administrator's andUser's Guide

SC33-2701

IBM Tivoli System Automation for Application Manager Reference SC34-2703

The System Automation for z/OS LibraryTable 2 shows the information units in the System Automation for z/OS library:

Table 2. System Automation for z/OS Library

Title Order Number

IBM Tivoli System Automation for z/OS Planning and Installation SC34-2716

IBM Tivoli System Automation for z/OS Customizing and Programming SC34-2715

IBM Tivoli System Automation for z/OS Defining Automation Policy SC34-2717

IBM Tivoli System Automation for z/OS User's Guide SC34-2718

IBM Tivoli System Automation for z/OS Messages and Codes SC34-2719

IBM Tivoli System Automation for z/OS Operator's Commands SC34-2720

IBM Tivoli System Automation for z/OS Programmer's Reference SC34-2748

IBM Tivoli System Automation for z/OS Product Automation Programmer'sReference and Operator's Guide

SC34-2714

© Copyright IBM Corp. 2005, 2015 xi

Table 2. System Automation for z/OS Library (continued)

Title Order Number

IBM Tivoli System Automation for z/OS TWS Automation Programmer's andOperator's Reference Guide

SC34-2749

IBM Tivoli System Automation for z/OS End-to-End Automation Adapter SC34-2750

IBM Tivoli System Automation for z/OS Monitoring Agent Configuration andUser's Guide

SC34-2751

SA z/OS Home Page:

For the latest news on SA z/OS, visit the SA z/OS home page athttp://www.ibm.com/systems/z/os/zos/features/system_automation

Related Product InformationFor information that supports Tivoli System Automation for z/OS, visit the z/OSlibrary in IBM Knowledge Center:

https://www.ibm.com/support/knowledgecenter/SSLTBW

AccessibilityAccessibility features help users with physical disabilities, such as restrictedmobility or limited vision, to use software products successfully. SystemAutomation for z/OS supports several user interfaces. Product functionality andaccessibility features vary according to the interface.

The major accessibility features in this product enable users in the following ways:v Use assistive technologies such as screen reader software and digital speech

synthesizer, to hear what is displayed on screen. Consult the productdocumentation of the assistive technology for details on using those technologieswith this product and screen magnifier software

v Operate specific or equivalent features using only the keyboardv Magnify what is displayed on screen.

The product documentation includes the following features to aid accessibility:v All documentation is available to both HTML and convertible PDF formats to

give the maximum opportunity for users to apply screen-reader softwarev All images in the documentation are provided with alternative text so that users

with vision impairments can understand the contents of the images.

Using assistive technologiesAssistive technology products, such as screen readers, function with the userinterfaces found in z/OS. Consult the assistive technology documentation forspecific information when using such products to access z/OS interfaces.

Keyboard navigation of the user interfaceUsers can access z/OS user interfaces using TSO/E or ISPF. Refer to z/OS TSO/EPrimer, z/OS TSO/E User's Guide, and z/OS ISPF User's Guide Vol 1 for informationabout accessing TSO/E and ISPF interfaces. These guides describe how to use

xii System Automation for z/OS: End-to-End Automation Adapter

http://www.ibm.com/systems/z/os/zos/features/system_automation

https://www.ibm.com/support/knowledgecenter/SSLTBW

TSO/E and ISPF, including the use of keyboard shortcuts or function keys (PFkeys). Each guide includes the default settings for the PF keys and explains how tomodify their functions.

Summary of Changes for SC34-2750-01This document contains information previously presented in System Automationfor z/OS V3R4.0 End-to-End Automation Adapter.

The following section lists important or major changes to this document.

New InformationKeystore and Truststore encryption for use by SSL

A procedure to provide secure storage and encryption for passwordmanagement in SSL is introduced in “How to Encrypt the KeystorePassword” on page 28 and “How to Create Keystore and Truststore for Useby SSL” on page 29.

Additional Authorization and Resource Security FeaturesThe use of user exits for authorization checking is updated in“Authorization checking by user exit” on page 33 describing the use ofuser exits for authentication. A new section describes the security checkingavailable for users and resources in “Authorization checking by SystemAutomation security” on page 35.

REFRESHSTART Policy ItemA new policy item REFRESHSTART is described to recycle MOVE groups.See “Policy Item REFRESHSTART” on page 52.

Quick Startup chapterChapter 2, “Quick Startup,” on page 7 is added as a new chapterdescribing a quick start up for the end-to-end automation adapter.

Prerequisites and Dependencies chapterThe former chapters 'Prerequisites and Dependencies' and 'PreparingNetView' are combined to give a new Chapter 3, “Prerequisites anddependencies,” on page 13.

Enabling The NetView Automation service E/AS chapterChapter 4, “Enabling NetView Event/Automation Service (E/AS),” onpage 17 is created as a new chapter with new information for the topicsfrom the former chapter 'Preparing NetView'.

Customizing System Automation Agent chapterChapter 5, “Customizing System Automation Agent,” on page 19 is addedas a new chapter to describe how the automation adapter can beconfigured for SA z/OS and NetView.

Encrypt SSL PasswordA description of the USS script ingencrypt.sh to encrypt an SSL passwordis added in “Encrypt SSL Password” on page 39.

Native command security checkingHow to execute NetView commands from the WebUI is described in a newtopic “Native command security checking” on page 36.

INGE2ENew parameters are added to the INGE2E command: SETDBGLVL,DELDBGLVL, VERIFY, PREPARE, and DISPCFG. An “Example verificationoutput” on page 75 is also given for use of INGE2E.

About this publication xiii

Changed InformationREFRESHSTART STARTUP policy replaces ACORESTART message

For E2E_ADPT entry type, see “Policy Item REFRESHSTART” on page 52,and also refer to “CHECK_HEALTH function failure” on page 60, and“INGE2E” on page 72.

End-to-End automation management “End-to-end automation management server” on page 1 is updated toinclude references to the new System Automation WebUI, that is used toview automation information through a browser. The graphical userfront-end is part of the IBM Service Management Unite component that isincluded in the IBM Service Management for z/OS Suite V1.3.0.

End-to-End automation adapter description“The end-to-end automation adapter” on page 2 now includes references tohow the automation adapter works in linking the management server andautomation domains. Additional references are provided to the SA z/OSnode, and automation SA z/OS domain and domain name. A newdescription is provided of the NetView event/automation service.

USS PrerequisitesUSS Prerequisites are enhanced to provide with additional commands(point 6).

Suffix parameter in ingadapter.sh scriptThe suffix option is updated with options on how to include a suffix infilenames, when using the ingadapter.sh script. See “Syntax” on page 38.

Appendix BAppendix B, “SA z/OS specific implementation of the end-to-endautomation resource data model,” on page 65 is updated to containinformation about System Automation WebUI. This appendix lists the datashown in the widgets of this user interface (Domain, Node and Resourceobjects). The graphical user interface is part of the IBM ServiceManagement Unite component that is included in the IBM ServiceManagement for z/OS Suite V1.3.0.

Deleted InformationRESET parameter for INGE2E

The parameter RESET is removed for INGE2E.

Installing the End-to-End Automation AdapterThis chapter is removed. Some topics are moved to Chapter 3,“Prerequisites and dependencies,” on page 13.

Prerequisites and Preparing NetViewThe former chapters 2 and 3 are removed and some topics are added andcombined to give Chapter 3, “Prerequisites and dependencies,” on page 13.

Preparing NetViewThe former chapter 4 is exchanged with Chapter 4, “Enabling NetViewEvent/Automation Service (E/AS),” on page 17 with topics moved asappropriate.

xiv System Automation for z/OS: End-to-End Automation Adapter

Chapter 1. Introducing the end-to-end automation adapter

This information provides a brief introduction to concepts and architecture ofend-to-end automation management and the end-to-end automation adapter (alsocalled the automation adapter in this information). For more detailed information,refer to IBM Tivoli System Automation for Application Manager Administrator's andUser's Guide.

End-to-end automation management server

End-to-end automation server can be used to:v automate the operation of resources within heterogeneous environmentsv manually operate resources within heterogeneous environments

Each heterogeneous environment (called first-level automation domain) has a localautomation technology of their own, for example, System Automation for z/OS. Itis connected to the end-to-end automation manager by an automation adapter.

Figure 1 on page 2 shows the main parts that make up the end-to-end automationmanagement server and the relationship of the first-level domain to it.

The SA WebUI is a Web-based graphical user front-end to the end-to-endautomation domain and to the first level automation domains. The graphical userfront-end is part of the IBM Service Management Unite component that is includedin the IBM Service Management for z/OS Suite V1.3.0.

For details about these parts, see IBM Tivoli System Automation for ApplicationManager Administrator's and User's Guide and the IBM Service Management UniteInstallation and Configuration Guide.

© Copyright IBM Corp. 2005, 2015 1

|

|

|

|||

||

The end-to-end automation adapter

The automation adapter acts as the link between the end-to-end automationmanagement server and its first-level automation domain.

SA z/OS Node

This is the SA z/OS equivalent of a system.

SA z/OS first-level automation domain name

The automation domain is the group of SA z/OS agents and managers that belongto the same XCF Group ID (GRPID). SA z/OS calls this group SAplex.

Node

NodeFirst-levelautomation manager

Automation adapter

Node

First-levelautomation domain

Auto-mationpolicy

Automationengine

Automationdatabase

First-levelautomation managerresource adapter

Automation engineresource adapter

Automation J2EE framework

End-to-end automation manager

SAWebUI

End-to-end automation management server

Browserclient

JazzSM Dashboard

WebSphere Application Server

Figure 1. Parts of the end-to-end automation management component

2 System Automation for z/OS: End-to-End Automation Adapter

|

|||

||

|

|

|

||

You may change the default name of the automation domain name to your needsby setting the parameters plugin-domain-name within configuration fileing.adapter.plugin.properties.

If this parameter is not set, the default name of the automation domain forSA z/OS is the blank delimited combination of physical sysplex name andINGXSGnn where nn is the 2-character XCF group id, for example, "KEYAPLEXINGXSG34".

You find the sysplex name and the XCF group name emphasized in INGAMSoutput which is the output of the SA z/OS command INGAMS. The YES undercolumn PA shows that this agent is the primary agent.

SA z/OS first-level automation domain

Each SA z/OS first-level automation domain represents a SAplex.

It has an end-to-end automation adapter and a primary SA z/OS automationagent. The automation adapter and primary automation agent runs on the samesystem. The automation adapter can only run on one system in the SAplex. Thesystem where it runs is automatically selected as primary agent (PA=YES).

PurposeThe purpose of the automation adapter is to:v monitor resources within its first-level automation domainv propagate resource attribute changes to the end-to-end automation managerv start and stop resources within the first-level automation domain by request of

the end-to-end automation managerv provide information about resources that are available within the first-level

automation domain in response to queries from operators.

CommunicationThe automation adapter sends asynchronous events to the end-to-end automationmanagement server and receives synchronous requests as shown in Figure 3 onpage 4.

INGKYAM0 SA z/OS - Command Dialogs Line 1 of 3Domain Id . : IPXDG ------------ INGAMS ------------ Date . . : 07/16/15Operator Id : BDOW Sysplex = KEY1PLEX Time . . : 17:30:36

Cmd: A Manage B Show Details C Refresh Configuration D Diagnostic

CMD System Member Role Status Sysplex XCF Group Release Comm PA— -------- --------- ----- ---------- -------- --------- ------- ---- —

KEYA KEYA$$$$2 PAM READY KEYAPLEX INGXSG34 V3R5M0 XCFKEYA KEYA AGENT READY KEYAPLEX INGXSG34 V3R5M0 XCF YESKEYB KEYB AGENT READY KEYAPLEX INGXSG34 V3R5M0 XCF

Figure 2. INGAMS output

Chapter 1. Introducing the end-to-end automation adapter 3

|

|||

|||

||||

||||

|||

Synchronous communicationThe automation adapter receives a request from the end-to-end automationmanagement server and schedules it via synchronous PPI communication to anSA z/OS task execution request that runs on the automated operator functionE2EOPER or E2EOPRnn. Refer to Figure 3. The task execution request contains oneor more end-to-end automation requests.

The program-to-program interface:

The program-to-program interface (PPI) enables application programs to send orreceive data buffers from other application programs that are running on the samehost. The program-to-program interface (PPI) is an optional facility of the NetViewsubsystem address space and must be initialized with its PPIOPT start option.

PPI is used for synchronous communication between the primary SA z/OSautomation agent and the automation adapter.

E2E adapter_host

E2E server_host

E2E request EIF event

EIF event

End-to-endManagementServer

End-to-endAutomation

Adapter

PPISynchronous

communication

PrimaryAutomationManager

PAM_host

SA z/OSprimaryAgent

PPI:INGEVE2EINGE2Enn

NetViewE/AS

NetViewSSI

NetView

2002

2001

5529

Figure 3. End-to-end automation adapter communication


|

|||

|||||

||||

Asynchronous communicationThe automation adapter provides an EIF event receiver and an EIF event emitter,both of which can be customized via the automation adapter master configurationfile, ing.adapter.properties.

SA z/OS acts as an asynchronous data provider and sends SA z/OS-specificevents to the EIF event receiver of the automation adapter. The automation adapterprocesses the event and converts it to a format understood by end-to-endautomation the management server. It will be sent to the end-to-end automationmanagement server through the built-in EIF emitter component.

For more information about EIF, refer to Tivoli Enterprise Console Event IntegrationFacility Reference.

The NetView event/automation service

The message adapter service of the NetView event/automation service (E/AS) isused to convert and forward messages from NetView to a designated event server,such as the end-to-end automation adapter. The end-to-end adapter requires that aseparate E/AS address space is to be started.

The primary SA z/OS automation agentThe successful initialization of the automation adapter on a system makes theautomation agent on that system into the primary automation agent.

The automation adapter uses the primary automation adapter to communicatewith the primary SA z/OS automation manager (PAM).

The primary automation agent forwards events to the automation adapter after ithas registered with the primary automation agent and subscribed for them.

After a system failure, event subscriptions may have been lost and so theautomation adapter has to re-subscribe.

Note: There is a small chance that if two automation adapters are started in thesame sysplex, each of the associated SA z/OS agents might become the primaryagent. To avoid this, you should switch to the high availability solution for theautomation adapter. See Chapter 9, “Operating the end-to-end automation adaptervia SA z/OS,” on page 41 for more details.

Chapter 1. Introducing the end-to-end automation adapter 5

|

||||

||


Chapter 2. Quick Startup

This information describes briefly the configuration steps in order to start up theend-to-end adapter with minimum configuration changes.

Default parameters are not explained here and left as is as much as possible.

A few abbreviations are used in this information:v ING.SING* - SA z/OS target data sets as provided by SMP/E installationv CNM.CNM* - NetView target data sets as provided by SMP/E installationv custom-root - User configuration directory of the end-to-end adapterv install-root - Installation root directory of the end-to-end adapter (default

installation directory is /usr/lpp/ing).

Overview of Quick StartupThe following configuration items need to be completed for a quick startup of theend-to-end adapter:1. SA z/OS automation policy2. SA z/OS initialization member INGXINIT3. SA z/OS end-to-end adapter sample JCL procedurev ING.SINGSAMP(INGXADPT)

4. SA z/OS end-to-end adapter USS configuration filesv /custom-root/adapter/config/ingadapter.propertiesv /custom-root/adapter/config/ing.adapter.propertiesv /custom-root/adapter/config/ing.adapter.plugin.properties

5. NetView subsystem (SSI) JCL procedure for PPI enablement6. NetView Event Automation service (E/AS)v CNM.CNMSAMP(IHSAEVNT)v CNM.SCNMUXCL(IHSAINIT)v CNM.SCNMUXCL(IHSAMCFG)

7. Start and verify end-to-end adapter.8. Follow-on activities.


|

|

||

|

|

|

|

|

||

||

||

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

SA z/OS automation policyImport the Automation Operators (AOP) entry E2E_AUTOOPS (AutomatedFunctions for E2E) from the *E2E best practices policy, link it to the systems whereyou want to start the End-to-End Adapter and build the automation configurationfile.

For details, refer to “SA z/OS automated operator functions” on page 19.

SA z/OS initialization member INGXINIT

Enable PPI communication within DSIPARM member INGXINIT by setting:PPI=YES

For details, refer to “SA z/OS initialization member INGXINIT” on page 19.

SA z/OS sample JCL procedure INGXADPTThe sample procedure INGXADPT within SA z/OS samples data set allows you tostart the automation adapter as a batch job or started task.

ing.adapter.plugin.properties

GRPID=XX

ing.adapter.properties

E2Eserver_host2002

E2Eadapter_host

eif-send-to-hostname =

eif-send-to-port =

eez-remote-contact-hostname =

eez-remote-contact-port =

eif-receive-from-port =

eif-receive-from-hostname =

2001

5529127.0.0.1

IHSAMCFG

5529ServerLocation =

ServerPort =

127.0.0.1

E2E adapter_host

E2E server_host


EIF event



Adapter

PPISynchronous

communication

2002

2001

5529

INGXINIT IHSAINITPPI=YESGRPID=XX PPI=INGEVE2E

SA z/OSprimaryAgent


NetViewE/AS

NetViewSSI

NetView

Figure 4. End-to-end automation adapter communication


|

||||

||

||||

|

||

|

|

|

||

||

Copy ING.SINGSAMP(INGXADPT) and follow the customization instructions within thesample job. Set JCL symbols DIRI and DIRC:// DIRI=’<install-root>/adapter’// DIRC=’<custom-root>/adapter’

For more details on how to start the automation adapter, refer to Chapter 8,“Operating the end-to-end automation adapter,” on page 37.

SA z/OS USS configuration files (automatically)Logon to the NetView console on the system where you plan to run the end-to-endadapter.

Issue the command:NETVASIS INGE2E PREPARE IPATH=/install-root/adapter

CPATH=/custom-root/adapterSERVER=hostnameJAVA=/32bit_java_home

IPATHInstall root directory of the end-to-end adapter, for example,/usr/lpp/ing/adapter

CPATHCustom root directory for read/write, for example, /local/ing/adapter.

Subdirectories will automatically be created.

SERVEREnd-to-end management server hostname, for example, Inex2e4x

JAVA32 bit java home directory, for example, /local/java/a60/J6.0

You may omit this parameter if the default java runtime is already a 32-bit javaversion 1.6. For example:NETVASIS INGE2E PREPARE IPATH=/usr/lpp/ing/adapter CPATH=/local/ing/adapter

SERVER=Inxe2e4x JAVA=/local/java/a60/J6.0

This command completes the following:1. Creates the subdirectories within the custom-root directory2. Copies all necessary configuration files3. Updates the configuration files within the input parameters for quick startup.

You may want to browse and check the recently created configuration files viacommand:NETVASIS INGE2E DISPCFG CPATH=/local/ing/adapter

Now you are done with the configuration of the USS configuration files.

For more details about the command INGE2E PREPARE, see “INGE2E” on page72.

Chapter 2. Quick Startup 9

||

||

||

||

||

|

||||

|||

||

|

||

||

||

||

|

|

|

|

||

|

|

||

SA z/OS USS configuration files (manually)If you do not wish to use the command INGE2E PREPARE you may performmanually as an alternative the customization steps of the USS files. If you havealready successfully executed command INGE2E PREPARE, leave this section.

You can create the following subdirectories for the custom-root directory:1. /custom-root/adapter2. /custom-root/adapter/config3. /custom-root/adapter/data4. /custom-root/adapter/ssl

You copy the following files from the install-root directory into the custom-rootdirectory.

cd /install-root/adapter/config

v cp /ingadapter.properties /custom-root/adapter/config/ingadapter.properties

v cp /ing.adapter.properties /custom-root/adapter/config/ing.adapter.properties

v cp /ing.adapter.plugin.properties /custom-root/adapter/configuring.adapter/plugin.properties

v cp /ing.adapter.ssl.properties /custom-root/adapter/config/ing.adapter.ssl.properties

You modify the following environment variables within the configuration fileingadapter.properties.E2E_INSTALL_ROOT=/install-root/adapterE2E_CUSTOM_ROOT=/custom-root/adapterE2E_JAVA_HOME=32-bit java-home-directory

You may modify the files that you have copied to your needs.

For details about the parameters of the configuration files, refer to Chapter 6,“Customizing the end-to-end automation adapter,” on page 23. The minimumchanges are as follows:v /custom-root/adapter/config/ing.adapter.properties

– eif-send-to-hostname=management_server_hostname

– plugin-configfile-sa4os=/custom-root/adapter/config/ing.adapter.plugin.properties

v /custom-root/adapter/config/ing.adapter.plugin.properties

– GRPID=xx

This parameter must match the GRPID of the DSIPARM member INGXINIT.

NetView SSI JCL procedureEnable PPI for the NetView subsystem interface address space (SSI) if not alreadydone.

Access your NetView SSI startup procedure and enable the PPI infrastructure viathe following parameter:// PPIOPT=’PPI’


||

|||

|

|

|

|

|

||

|

||

||

||

||

||

|||

|

|||

|

|

||

|

|

|

||

||

||

|

For more information, consult NetView sample job CNM.CNMSAMP(CNMSJ010).

NetView Event/Automation Service(E/AS)You must enable a dedicated E/AS address space for the end-to-end automationadapter. The E/AS is the broker between the SA z/OS NetView agent and theend-to-end automation adapter.

Perform the following tasks:v Allocation of the SCNMUXCL configuration data setv Copy the SA z/OS specific message adapter format file

ING.SINGSAMP(INGMFMTE)v Copy and configure the E/AS initialization file CNM.SCNMUXCL(IHSAINIT)v Copy and configure the E/AS message adapter configuration file

CNM.SCNMUXCL(IHSAMCFG)v Configure the E/AS started task JCL CNM.CNMSAMP(IHSAEVNT)

For detailed instructions, refer to Chapter 4, “Enabling NetView Event/AutomationService (E/AS),” on page 17.

End-to-End Adapter startupYou start the end-to-end automation adapter via the sample procedure INGXADPT:/S INGXADPT,F=START

For more details on how to start the automation adapter, refer to Chapter 8,“Operating the end-to-end automation adapter,” on page 37.

Before you start end-to-end automation adapter, you must make sure that allprevious customization steps are in effect:1. If you have changed the NetView DSIPARM member INGXINIT then stop the

SA z/OS communication task:STOP TASK=INGPXDST

Optionally, you may shutdown NetView.2. If you have adapted the NetView SSI startup JCL, stop the SSI address space.3. Refresh the corresponding Primary Automation Manager with the modified

SA z/OS configuration file (socntl_file). You may use one of the followingcommands:INGAMS option C "Refresh Configuration"F pam_jobname,REFRESHF pam_jobname,REFRESH.socntl_file

4. If you have adapted the NetView SSI start procedure then recycle SSI.5. Start the SA z/OS communication task:

START TASK=INGPXDST

Optionally recycle NetView and make sure that the NetView SSI is started aswell.

6. Start the configured NetView event automation service address space (E/AS):S IHSAEVNT

You may browse the Netlog and look for the following completion message:ISH0124I Message Adapter task initialization complete.

7. Start the SA z/OS end-to-end automation adapter:

Chapter 2. Quick Startup 11

|

||

|||

|

|

||

|

||

|

||

||

|

|

||

||

||

|

|

|

|||

|

||

|

|

|

||

|

|

|

|

|

S ISHAEVNT

Browse the Netlog and look for the following completion messages:EEZA0102I The adapter is readyEEZA0118I The connection to the server hostname: 2002 has been established

Verifying end-to-end automation adapterEnsure that the E/AS address space is running that you have configured for theautomation adapter. It is not necessary to have a running end-to-end adapter. TheNetView operator that runs the Verify command should be allowed to access USSfiles.

On the NetView console, enter command:NETVASIS INGE2E VERIFY JOBEAS=eas-jobname CPATH=/custom-root/adapter

For more details, see “INGE2E” on page 72.

Following upYou might want to perform the following list of customization tasks aftersuccessful "Quick Startup":v SSL configurationv End-to-End Adapter Securityv End-to-End Adapter High Availability using SA z/OS.


|

|

||

||

||||

|

|

|

||

||

|

|

|

Chapter 3. Prerequisites and dependencies

Prerequisites

The following prerequisites are required for the automation adapter:v SA z/OS 3.5 and IBM Tivoli NetView® and z/OS as described in the program

directory of SA 3.5v Java™ Runtime Environment (JRE) 1.6 or higher installed on z/OS. The 32-bit

java version is required. It is recommended to use IBM Javav The JRE Software Development Kit (SDK) if you choose to use the facility to

create sample keys for test purposesv The Event/Automation Service (E/AS) component of NetView. See the topic

"Enabling Event/Automation Service" in the NetView manual Installation:Configuring Additional Components and Chapter 4, “Enabling NetViewEvent/Automation Service (E/AS),” on page 17.

v Full z/OS UNIX System Services (USS) with USS file systemv SSI address space with PPI function of NetViewv TCP/IPv RACF if authentication is enabled.

Setup Java RuntimeThe automation adapter is provided in Java Archive (JAR) file format and requiresthe 32-bit version of Java Runtime Environment (JRE) version 1.6 to be installed onz/OS as the default java runtime.

If the default java runtime cannot be changed, set the environment variableE2E_JAVA_HOME in the automation adapter configuration fileingadapter.properties to the required java runtime.

Setup Environment VariablesThe automation adapter start script is located in the installation root directory anddefaults to /usr/lpp/ing/adapter/ingadapter.sh.

This script is assumed to be READONLY. No customization needs to be done inthe script.

However, before starting this script some USS environment variables must be setup. You find the default setting of these environment variables in the automationadapter configuration file /usr/lpp/ing/adapter/ingadapter.properties.

This configuration file will be specified in the SDTENV DD statement within theJCL procedure INGXADPT that starts the automation adapter as a started task.


||

|

|

|||

|||

|

||

||

|||

||

Setup Install-Root and Custom-Root DirectoryThe automation adapter requires a directory structure within the USS file system.

Within ingadapter.properties you can define:v install-root directory which is normally read-onlyv custom-root directory which contains all customized configuration files and the

log files.

You may run with the default USS file system.

However, if you have a different install-root directory and optionally you maywant to distinguish between install-root and custom-root directory you must adaptthe ingadapter.properties to your needs.

Default USS File SystemThe SMP/E installation creates a default file structure for the various files that areassociated with the automation adapter, with the following subdirectories:1. /usr/lpp/ing/adapter2. /usr/lpp/ing/adapter/config3. /usr/lpp/ing/adapter/data4. /usr/lpp/ing/adapter/lib5. /usr/lpp/ing/adapter/ssl

where the different paths are for:1. Executable files, for example, the automation adapter start and stop scripts2. Configuration files, for example, the master configuration file3. Working files, for example, release information file or log files. This directory is

initially empty.4. JAR files and DLLs for the automation adapter5. Security certificates. The directory is initially empty.

User-Defined USS File SystemThis description assumes that you want to distinguish between install-root andcustom-root directory.

You can create the following sub-directories for the custom-root directory:1. /custom-root/adapter2. /custom-root/adapter/config3. /custom-root/adapter/data4. /custom-root/adapter/ssl

You can copy the following files from the install-root directory into the custom-rootdirectory.cd /install-root/adapter/config

v cp /ingadapter.properties /custom-root/adapter/config/ingadapter.properties

v cp /ing.adapter.properties /custom-root/adapter/config/ing.adapter.properties


|

|

|

|

||

|

|||

|

||

|

|

|

|

|

|

|

|

||

|

|

|

||

|

|

|

|

|

||

|

||

||

v cp /ing.adapter.plugin.properties /custom-root/adpater/config/ing.adapter.plugin.properties

v cp /ing.adapter.ssl.properties /custom-root/adapter/config/ing.adapter.ssl.properties

You modify the following environment variables within the configuration fileingadapter.properties.E2E_INSTALL_ROOT=/install-root/adapterE2E_CUSTOM_ROOT=/custom-root/adapterE2E_JAVA_HOME=32-bit java-home-directory

You modify the following remaining files to your needs.

For details about the parameters of the configuration files refer to Chapter 6,“Customizing the end-to-end automation adapter,” on page 23.v /custom-root/adapter/config/ing.adapter.propertiesv /custom-root/adapter/config/ing.adapter.plugin.propertiesv /custom-root/adapter/ssl/ing.adapter.ssl.properties

The automation adapter writes output data into custom-root/adapter/data.

All other configuration files reside in the install-root directory because there isnormally no need to modify them. For more details, refer to Chapter 6,“Customizing the end-to-end automation adapter,” on page 23.

Figure 5 illustrates the ingadapter.properties file with the environment variablesthat you can use to specify install-root directory and custom-root directory andother startup procedures.

#Setup the installation root directory.#This is the root of the automation adapter installation.#Default is /usr/lpp/ing/adapter▌1▐E2E_INSTALL_ROOT=/usr/lpp/ing/adapter

#Setup the customization directory.#It should contain configuration files, logger output files#and SSL related files.#Default is value of E2E_INSTALL_ROOT▌2▐#E2E_CUSTOM_ROOT=/usr/lpp/ing/adapter

#Maximum heap size in mega bytes of the java process#Default is 128.▌3▐#E2E_JAVA_XMX=128

#Optional, setup keystore and truststore password.#The password will be used for function GenerateSampleKeys#Needed only if it is planned to generate sample keys for SSL.▌4▐#E2E_SSL_PASSW=password

#Switch debugging on if log files and trace files are needed.#Comment it out for production.▌5▐#E2E_DEBUG=ON

#Setup the Java home directory to your needs.#Java 1.5 is required.#Note, SA CANNOT run with 64-bit java#It is assumed that java is installed into following directories# $JAVA_HOME/lib# $JAVA_HOME/bin# @01A In order to run with different java runtime set E2E_JAVA_HOME▌6▐#E2E_JAVA_HOME=/local/java/j6.0

Figure 5. Sample environment variables, ingadapter.properties

Where the path and files that you might need to customize are:

Chapter 3. Prerequisites and dependencies 15

||

||

||

|||

|

||

|

|

|

|

|||

|||

||||||||||||||||||||||||||||||||||

|||

▌1▐ The automation adapter installation path.

▌2▐ The automation adapter customization path for modified configurationfiles, logger and SSL related files.

▌3▐ The maximum memory that the automation adapter is allowed to allocate.You can specify the maximum memory allocated by JVM in MB.

▌4▐ The password for the truststore that is generated by thegenerateSampleKeys function. This is only needed if you plan to generatesample keys for test purposes.

▌5▐ The switch to set on the logger function. Needed only if problem analysisis required.

▌6▐ The Java runtime and SDK paths to invoke Java and the Java keytoolrespectively if the default java is not appropriate.

Shared USS File SystemOn a shared USS file system you have only one install-root and one custom-rootdirectory for all systems in the SAplex. Therefore you have only one set ofconfiguration files for all systems.

If you want to use a shared USS file system for all systems and you use a virtualIP (VIPA) for the automation adapter remote contact IP address, you need tospecify the VIPA in the parameter eez-remote-contact-hostname in theconfiguration file ing.adapter.properties. If you do not want to use a VIPA forthe automation adapter remote contact IP address you let the automation adapterautomatically determine the hostname.

By default, the automation adapter always writes messages and traces to the samelog files regardless of which system it is currently running on. If you want separateoutput directories per system, you must start the automation adapter with thesystem name as suffix parameter, for example, if the system name is SYS1./ingadapter.sh start SYS1

or if you use the started task:/S INGXADPT,F=START,SX=SYS1

For more details, refer to “USS script” on page 37.

In this case, the output directories will be system-dependent, for example:1. /custom-root/adapter2. /custom-root/adapter/data/SYS13. /custom-root/adapter/data/SYS1/eez/log


||

|||

|||

||||

|||

|||

|

|||

||||||

||||

|

|

|

|

|

|

|

|

Chapter 4. Enabling NetView Event/Automation Service (E/AS)

The end-to-end automation adapter uses the NetView message adapter service ofE/AS as a gateway between the primary system automation agent and theend-to-end automation adapter.

The NetView message adapter service of E/AS converts incoming messages fromNetView into EIF events and forwards them to the automation adapter.

There is additional information about how to enable the NetView message adapterservice of E/AS for end-to-end automation. For more details, see the topic "SettingUp UNIX System Services for the NetView Program" in Tivoli NetView for z/OSInstallation: Configuring Additional Components.

Starting the E/AS Address SpaceThe event/automation service may be started with a JCL procedure from an MVSsystem console.

A sample JCL procedure for starting E/AS is provided in member IHSAEVNTwithin NETVIEW.CNMSAMP.

Customize the Sample ProcedureYou have to customize the sample procedure IHSAEVNT with the followingparameters:

INITFILEGlobal initialization file (Default: IHSAINIT)

MSGCFGMessage adapter configuration file (Default: IHSAMCFG)

PPIMust be INGEVE2E

If you want to use your own PPI receiver ID different to INGEVE2E, you have todefine it to SA z/OS as an advanced automation option before starting SA z/OS.For more details, see “SA z/OS advanced automation options” on page 20.

The concatenation of data sets for DD IHSSMP3 in the sample procedure mustcontain both E/AS initialization files mentioned here and the end-to-end specificmessage adapter format file which is provided in ING.SINGSAMP(INGMFMTE).

If you want to use your own data set for DD IHSSMP3 allocate it with thefollowing data set characteristics:RECFM=VB,RECL=516

As an initial size you might allocate the following number of tracks:Primary Quantity . . 10Secondary Quantity . 2Directory Blocks . . 5Block Size . . . . . 27998


|

|

|||

||

||||

||

||

||

||

||

||

||

||

|||

|||

||

|

|

||||

Copy members IHSAINIT and IHSAMCFG from the NetView sample library intoyour data set.

Copy member INGMFMTE into your data set or add ING.SINGSAMP to theconcatenation of DD IHSSMP3.

Configuring the global initialization file (Default: IHSAINIT)Customize which E/AS tasks should be started. Only the message adapter isrequired.# Tasks not started at initializationNOSTART TASK=ALERTA#NOSTART TASK=MESSAGEANOSTART TASK=EVENTRCVNOSTART TASK=ALRTTRAPNOSTART TASK=TRAPALRTNOSTART TASK=MESSAGECNOSTART TASK=ALERTC

Configuring the NetView message adapter service (Default:IHSAMCFG)

The automation adapter is listening to port 5529 and is located on the same z/OSsystem as the E/AS:ServerLocation=127.0.0.1ServerPort=5529

Specify the name of the NetView message adapter format file:AdapterFmtFile=INGMFMTE

Establish a permanent IP connection between the automation adapter and theE/AS address space:ConnectionMode=connection_oriented

Switch off the caching of events:BufferEvents=no


||

||

||

||

||||||||

||

|

||

||

|

|

||

|

|

|

|

Chapter 5. Customizing System Automation Agent

This information provides details of how to customize NetView and SA z/OSconfiguration members for the automation adapter.

SA z/OS initialization member INGXINITSet the following automation adapter-specific parameters in the SA z/OSinitialization member ING.DSIPARM (INGXINIT).

It is required to enable PPI communication by setting the following parameter:PPI=YES

Ensure that the value of the parameter GRPID is the same as specified in theautomation adapter plug-in configuration file /custom-path/adapter/config/ing.adapter.plugin.properties.

Optionally, you may set the PPI buffer queue limit (PPIBQL) higher if needed.

You may keep the default and if you receive one of the following error messages,increase the buffer queue limit.PPIBQL=nnnn|1500

For more details, Chapter 10, “Problem determination,” on page 55

All input requests from the end-to-end adapter flow into this PPI queue. Thebuffer queue limit is exceeded (that is, the queue limit is too small), then:v the automation adapter might not be able to send any further requests to the

SA z/OS Agent, and the agent issues a JNI exception with the return code 1735:INGX9820E JNI function ingippi failed with return code 1735

v the SA z/OS Agent might not be able to send any responses to the automationadapter, and an AOF350E message is issued.

SA z/OS automated operator functionsEnd-to-end automation uses dedicated automated operator functions (AOP) in theprimary agent to execute requests and to forward events to and from theend-to-end automation adapter.

These AOPs must be added to your SA z/OS policy.

Import the Automation Operators (AOP) entry E2E_AUTOOPs (AutomatedFunctions for E2E) from the *E2E best practices policy. Link it to the systems whereyou want to start the End-to-End adapter and build the automation configurationfile.

Automated operator function Automation Operator

E2EOPERE2EOPR01 ... E2EOPRnn

AUTE2EAUTE2E01 ... AUTE2Enn

EVTOPER AUTEVT1 (AUTEVT2 as a backup)


|

|

||

||

||

|

|

|||

|

||

|

|

||

||

|

||

||

|||

|

||||

|||

||||

|||

Note that the maximum value of nn can be 99 but should ideally be the same asthe number of concurrent working threads, as defined by parametereez-max-connections in the master configuration file (see “The automation adaptermaster configuration file” on page 23).

The automated operator functions (E2EOPER and E2EOPR01 through E2EOPRnn)are used to execute requests from the automation adapter.

The automated operator function EVTOPER is used to forward events to theautomation adapter and you must define it. Otherwise the initialization of theautomation adapter fails.

The corresponding automation operator tasks are defined in the NetViewDSIPARM dataset. The sample member AOFOPFSO contains by default thefollowing NetView tasks: AUTE2E, AUTE2E01, AUTE2E02, AUTE2E03. Definemore according to your needs.

If your environment is controlled by RACF, then consultING.SINGSAMP(INGESAF) member to add these operators to the RACFenvironment.

SA z/OS advanced automation optionsThe following advanced automation options can be used to change the defaultsettings of the primary automation agents.

Automation adapter advanced automation options shows the common globalvariables that are provided as advanced automation options. Adapt them to yourneeds.

Table 3. Automation adapter advanced automation options

Variable Value Effect Further details

AOF_E2E_EAS_PPI User-defined

PPI receiver ID of the event/automationservice to be used to forward events tothe end-to-end automation adapter.

AOF_E2E_EVT_RETRY 1 to n Specifies the number of retries, atintervals of one second, that are used totransfer events via PPI TECROUTE to themessage adapter of the event/automationservice. The events are to be forwarded tothe end-to-end automation adapter.

“Non-disruptive recoveryfrom errors” on page 41

AOF_E2E_EXREQ_NETLOG 1 The output to requests received from theend-to-end automation adapter andissued by the primary automation agent,is logged to the NetView log.

0 The output to those requests is notlogged to the NetView log.

0 is the default setting.

AOF_E2E_TKOVR_TIMEOUT hh:mm:ss If a hot restart of the automation managertakes longer than the value specified inthis variable, the end-to-end automationmanager is informed about the outageand has to resynchronize with thefirst-level automation.

“Non-disruptive recoveryfrom errors” on page 41


||||

||

|||

||||

|||

||

||

|||

||

||||

||||||

|

||||||||

||

||||||

|

|||

|

||||||||

||

Table 3. Automation adapter advanced automation options (continued)

Variable Value Effect Further details

INGREQ_PRI.E2EMGR Priority Specifies the priority that incomingrequests from the end-to-end automationmanager are executed at. The end-to-endautomation manager version 3.1.1 orhigher may overwrite this priority withthe incoming request. Default: LOW

“Request issued toresource objects” on page69

Chapter 5. Customizing System Automation Agent 21

|

||||

||||||||

|||

||


Chapter 6. Customizing the end-to-end automation adapter

Having installed the automation adapter files you will need to configure them foryour setup. This information provides details of how you should do this.

The configuration steps that you need to carry out for the automation adapter aredescribed in the following sections.

Configuration filesThe following configuration files are delivered with the automation adapter:v “The automation adapter master configuration file,” ing.adapter.propertiesv “The automation adapter plug-in configuration file” on page 25,

ing.adapter.plugin.propertiesv “The SSL configuration file” on page 27, ing.adapter.ssl.propertiesv “The JAAS configuration file” on page 29, ing.adapter.jaas.propertiesv “The Java logger configuration file” on page 30, ing.adapter.jlog.properties

Note: In the extracts and samples that are given in this document, EEZ (or eez)refers to end-to-end automation.

The automation adapter master configuration fileThe automation adapter needs a master configuration file./config/ing.adapter.properties

Without a properly verified master configuration file the automation adapter willnot start.

The master configuration file contains IP addresses and ports that might bedifferent for each system within the sysplex. If the automation adapter moves toanother system it is recommended to use VIPA. Alternatively you omit parametereez-remote-contact-hostname. Refer also to “Shared USS File System” on page 16.

Figure 6 on page 24 shows the sample automation adapter master configurationfile that is delivered.


|

|

||||

The parameters that are highlighted must be configured to correspond to yoursetup, as follows:

▌1▐ eez-remote-contact-hostnameThe host name or IP address that is used by the automation adapter toreceive synchronous requests from the end-to-end automation server(WebSphere® Application Server—WAS). If you omit this parameter theautomation adapter automatically determines the hostname to which it islistening.

▌2▐ eez-operator-authenticationThis parameter determines the type of operator authentication that is used.If it is set to false, the automation adapter uses the SA z/OS JAAS defaultlogin module, or, if it is set to true, it uses the RACF-provided routine. (Seealso “The JAAS configuration file” on page 29.)

▌3▐ eif-send-to-hostnameThe host name or IP address of the end-to-end automation server.Additionally, you may define an alternative end-to-end automation serverhost. In this case, specify the host name or IP address of both hosts,separated by a comma.

▌4▐ eif-receive-from-portThe port that is to be used by the automation adapter to receive EIFevents. It must meet the naming convention of the original EIF ServerPortparameter.

▌5▐ plugin-configfile-sa4zosThis is the location of the plug-in configuration file. Specify thecustom-root directory of your choice.

Table 5 on page 61 gives details of all the parameters that can be specified in themaster configuration file.

The file IHSAMCFG is the NetView message adapter configuration member indata set SCNMUXCL (this data set is provided with NetView).

# --- Adapter Configuration -----

▌1▐ eez-remote-contact-hostname = E2Eadapter_hosteez-remote-contact-port = 2001eez-remote-contact-over-ssl = false

▌2▐ eez-operator-authentication = trueeez-initial-contact = falseeez-max-connections = 3

# --- EIF Configuration ---------

eif-cache = trueeif-cache-size = 1000eif-retry-interval-seconds = 30

▌3▐ eif-send-to-hostname = E2Eserver_hosteif-send-to-port = 2002eif-receive-from-hostname = 127.0.0.1

▌4▐ eif-receive-from-port = 5529

# --- Plugin Configuration ------

▌5▐ plugin-configfile-sa4zos = /custom_root/adapter/config/ing.adapter.plugin.properties

Figure 6. Sample automation adapter master configuration file, ing.adapter.properties


|||||||||||||||||||||||||

|||

Parameters ServerLocation and ServerPort in IHSAMCFG must matcheif-receive-from-hostname and eif-receive-from-port ining.adapter.properties.

Parameters eif-send-to-port in ing.adapter.properties must match the port andhostname of the E2E management server.

Note: All property names and values are case sensitive. The Java Virtual Machine(JVM) of the automation adapter must be able to access the classes, paths, and soforth, that are specified in the configuration files.

The automation adapter plug-in configuration fileThe master configuration file refers to the plug-in configuration file,ing.adapter.plugin.properties. This file contains, for example, the Java classname of the adapter plug-in application, or the default domain name. Without atleast one proper plug-in configuration file the adapter will not start.

In the adapter master configuration file, the propert yplugin-configfile-sa4zospoints to the configuration file of a specific plug-in application. This plug-inapplication configuration file must contain at least the properties that are shown inFigure 8 on page 26.

Figure 8 on page 26 shows an example of an automation adapter plug-inconfiguration file and highlights the entries that you must customize.

ing.adapter.plugin.properties

GRPID=XX

ing.adapter.properties

E2Eserver_host2002

E2Eadapter_host

eif-send-to-hostname =

eif-send-to-port =

eez-remote-contact-hostname =

eez-remote-contact-port =

eif-receive-from-port =

eif-receive-from-hostname =

2001

5529127.0.0.1

IHSAMCFG

5529ServerLocation =

ServerPort =

127.0.0.1

E2E adapter_host

E2E server_host


EIF event



Adapter

PPISynchronous

communication

2002

2001

5529

INGXINIT IHSAINITPPI=YESGRPID=XX PPI=INGEVE2E

SA z/OSprimaryAgent


NetViewE/AS

NetViewSSI

NetView

Figure 7. TCP/IP port relationship for the end-to-end automation components

Chapter 6. Customizing the end-to-end automation adapter 25

|

||||||

||

▌1▐ GRPIDYou must set the 2-byte XCF group ID of the SA z/OS subplex that youwant to use in the plug-in configuration file. This must be the same as thegroup ID in INGXINIT.

▌2▐ PPIBQLThe number of elements in the PPI queue—this indicates how large theresponse to a request may be. It should be greater than the number ofqueue elements that you expect to be returned.

▌3▐ AUTOPFNThis a NetView operator task name or an SA z/OS automated functionname to be used by SA z/OS to execute the incoming automation adapterrequest. See “SA z/OS automated operator functions” on page 19.

▌4▐ TIMEOUT_SA_NOTAVAILYou can set a timeout value in seconds with this parameter. A numbergreater than zero causes the plug-in to terminate if, after the time periodthat is specified, it detects that the SA z/OS NetView Agent is no longeravailable.

The automation adapter must receive two CHECK_HEALTH requests orother end-to-end automation server requests in order to calculate whetherthe timeout value has expired. If the SA z/OS NetView Agent cannot becontacted by both of the CHECK_HEALTH requests the automationadapter issues message INGX9907I before it terminates itself.

The default value is 0 (zero).

▌5▐ plugin-domain-nameThe plug-in domain name, which must be unique across all end-to-endautomation domains (z/OS, Linux, etc.). If you enter ? or omit theparameter, SA z/OS substitutes a name that is based on the XCF sysplexgroup name, however you can use your own naming strategy.

▌6▐ AUDITMSG=trueIf parameter AUDITMSG was set to true then requests sent by theend-to-end automation server and received by the automation adapter willbe logged in the message file msgAdapter.log and msgFlatAdapter.log. Ifparameter AUDITMSG was set to false, these information messages are notlogged. Default is true. Corresponding information messages INGX99nnI,

# --- Specific settings for the SA/NetView communication ---# --- Modify these parameters to your needs ---

▌1▐ GRPID = XX▌2▐ PPIBQL = 1500▌3▐ AUTOPFN = E2EOPER

TIMEOUT = 600▌4▐ TIMEOUT_SA_NOTAVAIL=180

CODEPAGE = Cp1047

# --- Domain name may be modified or omitted ---

▌5▐ #plugin-domain-name = MyDomainName

▌6▐ AUDITMSG = true

# --- Do not modify these plugin settings ---plugin-impl-class = com.ibm.ing.sam.INGXPluginplugin-impl-class-singleton = trueplugin-event-classes = SystemAutomation_Resource_Status_Change SystemAutomation_...plugin-auto-start = true

Figure 8. Example automation adapter plug-in configuration file, ing.adapter.plugin.properties


nn=10,11,..,15, are issued independent of the success or the failure of thecommand. These messages will not be written to SYSLOG. The messagescan be viewed on the end-to-end automation operator console. Thefollowing table maps the end-to-end automation requests to theinformation messages.

Table 4. Information Messages for AUDITMSG=true parameter

end-to-end automation Request Name Information Message

RESET_FROM_NON_RECOVERABLE__ERROR

INGX9915I

EXCLUDE_NODE INGX9911I

INCLUDE_NODE INGX9911I

MOVE_AWAY INGX9912I

MOVE_HOME INGX9913I

MOVE_TO INGX9914I

RESUME INGX9910I

SUSPEND INGX9910I

Any other command INGX9910I

Table 6 on page 63 gives details about the parameters that you must include inyour plug-in configuration file.

The SSL configuration fileThe SSL configuration file is only required if eez-remote-contact-over-ssl=true,otherwise you can ignore this section.

The automation adapter start-stop script, ingadapter.sh, reads the SSL configurationfile, ing.adapter.ssl.properties, in order to set up the SSL parameters. Theautomation adapter retrieves the name of the SSL configuration file from thesystem property com.ibm.eez.adapter.configSSL (this is set in the ingadapter.shscript).

If one of the parameters specified in Table 7 on page 64 is not set in the SSLconfiguration file, the automation adapter start-stop script uses the corresponding(default) value from the following Java system properties:v -Djavax.net.ssl.trustStorev -Djavax.net.ssl.keyStorev -Djavax.net.ssl.keyStorePasswordv -Dcom.ibm.eez.adapter.ssl.keyStoreAlias

It is expected that the truststore file can be read without a password. The keystoreand the certificates in the keystore must have the same password.

Figure 9 on page 28 shows an example of an SSL configuration file. It must containat least the properties that are shown in Figure 9 on page 28. Table 7 on page 64gives details about these parameters. You may specify an encrypted passwordinstead of the clear text. See also extra section about usage of the encryptionalgorithm.


▌1▐ Note: The SSL directory is initially empty. The truststore and keystore filesare not delivered with the automation adapter and must be created by thecustomer. Specify a full path in case the SSL is not a subdirectory of theadapter directory.

How to Encrypt the Keystore PasswordIn order to generate an encrypted password for parameter eez-ssl-keystore-password, you may use the System Automation Application Manager utilitycfgeezdmn. This tool generates among other items the SSL configuration file fordistributed platforms. Copy the line with the generated password fromeez.fla.ssl.properties and paste it into the SSL configuration fileing.adapter.ssl.properties on z/OS.

Notes:

1. The end-to-end automation must use the same version of the encryptionalgorithm as used by cfgeezdmn.

2. In regard to the EBCDIC character conversion, the codepage IBM 1047 is usedfor all configuration files. Make sure that all characters are correctly converted.It may be necessary to convert characters manually using the ISPF editor, forexample, {AES} must be ’C0C1C5E2D0’ X. For example, if for parametereez-ssl-keystore-password special characters are not correctly convertedaccording to code page IBM 1047 then the password may not be recognizedcorrectly during decryption.

SA AM 3.2.1 and earlier uses RSA encryption algorithm.

SA AM 3.2.2 and later uses AES encryption algorithm.

SA z/OS end-to-end automation with APAR OA41944 supports both RSA and AESencryption algorithm.

Use the USS script /custom-path/adapter/ingencrypt.sh in order to encrypt thekeyword password.

For details, refer to “Encrypt SSL Password” on page 39.

Example Invocation:cd /usr/lpp/ing/adapter./ingencrypt.sh -encrypt my password

Copy the line with the encrypted password from stdout and paste it into the SSLconfiguration file /custom-path/adapter/config/ing.adapter.ssl.properties.

## --- Adapter SSL Configuration File ------------------------#

▌1▐ eez-ssl-truststore = ./ssl/ing.ssl.truststore.jks▌1▐ eez-ssl-keystore = ./ssl/ing.ssl.adapterkeys.jks

eez-ssl-keystorepassword = passphrase#eez-ssl-keystore-password = {AES}Kc20JePWrtHcBaYMoBoG1A==eez-ssl-keystorealias = eezadapter

Figure 9. Example SSL configuration file, ing.adapter.ssl.properties


||

|

|

||

||

How to Create Keystore and Truststore for Use by SSLBelow you find an example of how to generate end-to-end automation adapterkeystore and the truststore via the Java keytool which resides in the Java SDK ofyour z/OS Java installation.

You specify both in the end-to-end automation SSL configuration fileing.adapter.ssl.properties.# Application Manager SSL config file directoryEEZ_CONFIG_DIR=/usr/lpp/ing/adapter/ssl# Keys will expire in 25 yearsKEY_VALIDITY_DAYS=9125# Passphrase at least 6 charactersPASSPHRASE=passphrase

1. Generate keystore for end-to-end automation z/OSkeytool -genkey -keyalg RSA -validity ${KEY_VALIDITY_DAYS} \-alias eezadapter -keypass ${PASSPHRASE} -storepass ${PASSPHRASE} \-dname "cn=SAAM Adapter, ou=Tivoli System Automation, o=IBM, c=US" \-keystore "${EEZ_CONFIG_DIR}/ing.ssl.adapterkeys.jks"

2. Export Certificate file with public key for end-to-end automation:${JAVA_KEYTOOL} -export -alias eezadapter \-file "${EEZ_CONFIG_DIR}/ingadapter.cer" -storepass ${PASSPHRASE} \-keystore "${EEZ_CONFIG_DIR}/ing.ssl.adapter.jks"

3. Create the truststore that contains the public keys for the end-to-end automationand the SA Application Manager

How to create and add the SA Application Manager certificate is described in theSA Application Manager Installation and Configuration Guide in the chapter section"Securing the connection end-to-end adapters using SSL".

Import the end-to-end automation certificate to the truststore.${JAVA_KEYTOOL} -import -noprompt -alias eezadapter \-file "${EEZ_CONFIG_DIR}/ingadapter.cer" -storepass ${PASSPHRASE} \-keystore "${EEZ_CONFIG_DIR}/ing.ssl.truststore.jks"

Import the System Automation Application Manager certificate to the truststore.${JAVA_KEYTOOL}-import -noprompt -alias eezapplicationmanager \-file "${EEZ_CONFIG_DIR}/eezapplication.cer" -storepass ${PASSPHRASE} \-keystore "${EEZ_CONFIG_DIR}/ing.ssl.truststore.jks"

4. Copy the keystore from step 1 and the truststore from step 3 into the end-to-endautomation SSL directory. Update ing.adapter.ssl.properties accordingly.

Refer also to the SA Application Manager Manual "Installation and ConfigurationGuide", chapter 5.

The JAAS configuration fileThe JAAS definitions for the automation adapter are defined in the JAASconfiguration file, ing.adapter.jaas.properties.

This file specifies two entries for a login module that is required because allincoming requests will be authenticated using JAAS. Figure 10 on page 30 shows asample JAAS configuration file.


The login modules are:

▌1▐ The end-to-end automation login module is provided for test purposes orwhen you can trust the end-to-end automation WebSphere authentication.It thus accepts all user IDs and passwords.

▌2▐ The z/OS login module rejects all users unless they are defined in RACF®.

The automation adapter master configuration file, ing.adapter.jaas.properties,contains the parameter eez-operator-authentication=true to switch between theentries. Setting the parameter to false causes the automation adapter to use theJAAS entry EEZAdapterDefaultLogin, otherwise the entry EEZAdapterLogin isused.

The entry EEZAdapterDefaultLogin uses the default automation adapter loginmodule that accepts any user and any password. The entry EEZAdapterLogin usesthe z/OS login module (RACF).

The z/OS administrator may overwrite the JAAS login module with any thirdparty security login module.

The Java logger configuration fileThe Java logger configuration file, ing.adapter.jlog.properties, defines thetargets for the following log files:v Two message log files (one in XML format, the other a flat file)v One trace log file as a flat file, to be used by IBM Supportv One event log file as a flat file, to be used by IBM Support

The message log file can be accessed via the automation adapter graphical userinterface (GUI).

The trace log files are to be used by IBM Support for debugging purposes. Use theIBMSupport parameter of the ingadapter.sh USS script to generate all of these filesas a zip file in the data directory.

All log and trace files are in UTF-8 format. If you use an FTP client and an editorthat can handle UTF-8, you should not have any problems reading the logs.

In a telnet session to z/OS USS you can use the following command (although youmight lose a few characters):view -a filename

In z/OS you must convert the files from UTF to EBCDIC using the command:iconv -f utf-8 -t ibm-500 traceFlatAdapter.log > new.log

EEZAdapterDefaultLogin {

▌1▐ com.ibm.eez.adapter.EEZAdapterDefaultLoginModule required ;};

EEZAdapterLogin {

▌2▐ com.ibm.security.auth.module.OS390LoginModule required;};

Figure 10. Sample JAAS configuration file, ing.adapter.jaas.properties


Note: There is no need for you to configure the ing.jlog.properties file unlessIBM Support asks you to change the trace level.

Customizing USS

Using the data directory for log filesAbout this task

You only need to specify the Tivoli Common Directory (TCD) if you comment outthe JLOG_OUTPUT statement in the ingadapter.sh USS shell script. This statementallows you to directly set the Java log output directory and skip the search for theTCD. The default is the automation adapter data directory.

Setting UNIX access privilegesYou can define profiles in the UNIXPRIV class to grant RACF authorization forcertain z/OS UNIX privileges.

About this task

These privileges are automatically granted to all users with z/OS UNIX superuserauthority. By defining profiles in the UNIXPRIV class, you may specifically grantcertain superuser privileges with a high degree of granularity to users who do nothave superuser authority. This allows you to minimize the number of assignmentsof superuser authority at your installation and reduces your security risk.

For details see z/OS Security Server RACF Security Administrator's Guide.

See z/OS Unix System Services Planning for a list of the resource names available inthe UNIXPRIV class, the z/OS UNIX privilege associated with each resource, andthe level of access required to grant the privilege.

To define the profiles so that you can use the ps -A USS shell command:

Procedure1. If the UNIXPRIV class is not active, enter:

SETROPTS CLASSACT(UNIXPRIV) RACLIST(UNIXPRIV)

2. Define the RACF profile for the privileges:RDEFINE UNIXPRIV SUPERUSER.PROCESS.GETPSENT UACC(NONE)

3. To grant READ access to the user OPER1:PERMIT SUPERUSER.PROCESS.GETPSENT CLASS(UNIXPRIV) ID(OPER1) ACC(READ)

4. Perform an RACF refresh:SETROPTS RACLIST(UNIXPRIV) REFRESH

Setting access privileges for TCP/IP connectionsYou can use the netstat -a command to display TCP/IP connections, and thenetstat-D nnnn command to drop the connection nnnn.

However, from the USS shell, the netstat command is protected through the RACFSERVAUTH class.

You can define new security product resource names in the SERVAUTH class tocontrol user's access to the UNIX shell onetstat command options. For example, for


the netstat -a command you can use the profileEZB.NETSTAT.mvsname.tcpprocname.ALLCONN

For a table of resource names see "Monitoring the TCP/IP network" in z/OSCommunications Server: IP System Administrator's Commands.

For the DROP option, you can use the profile MVS™.VARY.TCPIP.DROP in thefollowing definitions:RDEFINE OPERCMDS (MVS.VARY.TCPIP.DROP) UACC(NONE)PERMIT MVS.VARY.TCPIP.DROP ACCESS(CONTROL) CLASS(OPERCMDS) ID(uid)SETROPTS RACLIST(OPERCMDS) REFRESH

It may also be adequate to define a single generic profile that covers allcommands, as follows:RDEFINE OPERCMDS (MVS.VARY.TCPIP.**) UACC(NONE)PERMIT MVS.VARY.TCPIP.** ACCESS(CONTROL) CLASS(OPERCMDS) ID(uid)

For more details, see the section "z/OS UNIX security considerations for TCP/IP"in the Redbook "Security Configuration in a TCP/IP Sysplex Environment."

Customize the link listAdd the following libraries to your link list:v SYS1.SCLBDLL2v SYS1.SCEERUNv SYS1.SCEERUN2v SYS1.SCLBDLLv hlq.SINGMOD1

Alternatively, edit the ingadapter.sh start script and add these libraries as follows:export STEPLIB=SYS1.SCLBDLL2:SYS1.SCEERUN:SYS1.SCEERUN2:SYS1.SCLBDLL:hlq.SINGMOD1:$STEPLIB

You can check that these libraries have been linked using the following command:D PROG,LNKLST


Chapter 7. Security

This information gives details of the security (authentication and authorization)that is provided for the automation adapter.

AuthenticationWhen the end-to-end automation server issues a request to the automation adapter,there is always a user ID and password associated with it.

You must define user IDs and passwords with RACF. These define who is allowedto send an end-to-end automation request.

The automation adapter performs authentication checking using RACF via theJAAS architecture. You have three alternatives:1. Define the JAAS logon module provided by RACF. (If you want to use RACF,

the user IDs that you define are authorized.) This is equivalent to setting theparameter eez-operator-authentication to true in the master configuration file,ing.adapter.properties.

2. Define the JAAS logon module provided by EEZAdapterDefaultLogin thatalways validates as true. This is equivalent to setting the parametereez-operator-authentication to false.

3. Define the JAAS logon module provided by any third party product.

Authority checking by the automation adapterAuthorization checking is used to determine whether the automation adaptergrants or rejects the execution of an operation for the user ID that is associatedwith the request.

The automation adapter supports two alternative techniques to protect fromunauthorized operations:1. The use of the automation adapter authorization exit as described in previous

releases2. The exploitation of the System Automation built-in third party security.

The second technique is used in any case. The first technique is still supported forcompatibility reasons.

Authorization checking by user exitThe automation adapter performs the authorization user exit for each commandthat is to be executed, except for query requests.

The authorization user exit is an external REXX program that you must provide.The name of the authorization user exit must be AOFEXE2E. A sample of thisprogram can be found in SINGSAMP.

If no authorization user exit exists, a user is considered to be authorized for eachrequest.


If the authorization user exit is provided, it decides whether the request is acceptedor rejected with message ING238E.

The following arguments are passed to the authorization user exit via the NetViewPIPE default safe:v User IDv Request namev SA z/OS command, resulting from the request

where the end-to-end automation request names are mapped to SA z/OScommands as shown in the following table:

End-to-end automation request name Command abbreviation for RACF profile

Online INGREQ

Offline INGREQ

CancelRequest INGSET

IncludeNode INGSET

ExcludeNode INGREQ

ResetFromNRE SETSTATE

MoveTo, MoveAway, MoveHome INGMOVE

NativeCommand Any user command provided by the WebUICommand Widget

For further details about the command parameters, see “Requests issued by theoperations console and the end-to-end automation manager” on page 69.

Note: The authorization user exit must return a zero return code if the user isallowed to execute the command. Otherwise a non zero return code has to bereturned.

A non-zero return code results in the message:ING238E TASK EXECUTION REQUEST EXECUTE_UNSOLICITED_REQUEST FAILED:

ERROR=5SERVICE=’AOFEXE2E’ RC=rcREASON=’Authorization failed for user user idfor command command’

Sample authorization user exitIf you do not want to provide an authorization user exit of your own, you can usethe sample that is provided by SA z/OS as member AOFEXE2E in the sampledata set SINGSAMP.

Copy the sample into a clist concatenation -- it will then be active and will expectthe appropriate RACF profiles. If you have not defined these profiles no requestswill be authorized.

The sample exit includes an RACF checking routine that uses the RACF classFACILITY and the following profile pattern to check whether the user has thecorrect RACF access rights:hlq.command.resourceName.resourceType.resourceSystem


|||

where hlq is a unique prefix, for example, INGE2E, and command is one of theSA z/OS commands given in the table above (that is, INGREQ, INGSET, orSETSTATE).

With SA z/OS 3.4, the RACF access rights is per default UPDATE. In earlier SAreleases, it was ALTER. You can modify the RACF access rights and the high levelqualifier hlq to your needs in the sample REXX exit AOFEXE2E.

Appropriate RACF profiles:

If you use the SA z/OS sample authorization exit, you must define RACF profilesfor all users that should pass the authorization check.

Using the SA z/OS sample authorization exit there is no means to disableauthorization checking of an end-to-end automation request. You must define atleast the profile INGE2E* for the user that is associated with the request.

By adding an RACF user ID to the access list of such an RACF profile and givingthe UPDATE authority, the user is allowed to execute the command for theresource resourceName.resourceType.resourceSystem.

Examples of profiles for command INGREQ:

INGE2E.INGREQ.DB2.APL.KEY1The user is allowed to start or stop application DB2® on system KEY1.

INGE2E.INGREQ.DB2.**The user is allowed to start or stop DB2 resources of type application orgroup on all systems.

INGE2E.INGREQ.**The user is allowed to start or stop all resources on all systems.

Authorization checking by System Automation securityThe automation adapter performs the old authorization user exit plus additionalsecurity checking:1. Basic third party security check for command INGRXTX02. Extended third party security check for solicited and unsolicited end-to-end

automation adapter requests3. If the old authorization exit AOFEXE2E exists, it is processed4. System Automation resource security check for solicited and unsolicited

end-to-end automation adapter requests.

Basic third party security checkingThe purpose of the basic authorization is to check whether an alreadyauthenticated end-to-end automation user has the permission to access theend-to-end automation backend INGRXTX0.

The basic authorization is sufficient to perform any end-to-end automation adapterfunction except solicited and unsolicited end-to-end automation adapter requestsfor which extended security is required.

A userid that sends a request to the End-to-end automation adapter must fulfill thefollowing third party SAF check:

Chapter 7. Security 35

class NETCMDSpermission READprofile: netid.netvdom.INGRXTX0

Extended third party security checkingThe purpose of extended authorization is to check whether an alreadyauthenticated end-to-end automation user has the permission to perform solicitedand unsolicited end-to-end automation adapter requests.

For a mapping between end-to-end automation adapter requests and SystemAutomation commands, see Appendix B, “SA z/OS specific implementation of theend-to-end automation resource data model,” on page 65.

A userid that sends a solicited and unsolicited end-to-end automation adapterrequests to the End-to-end automation adapter must fulfill the following thirdparty check:

class NETCMDSpermission READprofile: netid.netvdom.xxxxxxxx

where xxxxxxxx is one of the following System Automation commands:v INGRYRU0 for synonym INGREQv INGRYSE0 for synonym INGSETv INGRYMVX for synonym INGMOVEv AOFRASTA for synonym SETSTATE

System Automation resource security checkingThe purpose of resource security is to check whether an already authenticatedend-to-end automation user has the permission to perform an action on the relatedSystem Automation resource.

For details about System Automation resource security, see IBM Tivoli SystemAutomation for z/OS Planning and Installation.

A userid that sends a solicited and unsolicited end-to-end automation adapterrequest to the End-to-end automation adapter must fulfill the following third partySAF check:

class SYSAUTOpermission UPDATE or CONTROLprofile: AGT.sysplex.xcfgrp.RES.name.type.system

INGREQ permission UPDATEINGSET permission CONTROLSETSTATE permission UPDATEINGMOVE permission UPDATE

Native command security checkingA native command provided by the WebUI command Widget is executed underthe NetView operator task and logon user id of the WebUI.

For example if BOB did logon to the WebUI and issued an arbitrary NetViewcommand, then the command is executed within the security context of NetViewoperator BOB. The standard NetView command authorization applies.


|||

|||

Chapter 8. Operating the end-to-end automation adapter

The automation adapter is started as a batch job or a started task which runs theUSS script ingadapter.sh via BPXBATCH.

How to use the automation adapterThere are three ways that you can operate the automation adapter:v With a USS script from the USS console, see “USS script”v As a batch job or started task, see “JCL Procedure using BPXBATCH” on page

39v As a defined resource in SA z/OS, see “SA z/OS defined resource” on page 40

USS script

Prerequisites for USS1. The user who is executing the automation adapter start script must have RACF

access rights to perform the TCP/IP command netstat -D, see “Setting accessprivileges for TCP/IP connections” on page 31.

2. The user who is executing the automation adapter start script must also haveRACF access rights to perform the TCP/IP command netstat -a, see “Settingaccess privileges for TCP/IP connections” on page 31.

3. The user who is executing the automation adapter start script must have RACFaccess rights to perform the UNIX command ps -A, see “Setting UNIX accessprivileges” on page 31.

4. The user ID must have write access to the data directory and to the logdirectory (if it does not reside in the data directory). It must also have readaccess to all other directories.

5. The automation adapter can be started by different user IDs but these IDs mustall belong to the same group.

6. If facility class BPX.DEAMON is defined in RACF the dynamic load librariesthat are used by the automation adapter must be RACF program-controlled.You may check the program-controlled flag by command ls -Elisa *.soThis can be done for modules of the HFS by setting the extended attribute p.During SMP/E installation the extended attribute p is set automatically for alllibraries (*.so) and ingwto within the automation adapter lib directory. If this isnot the case you may set it using the extattr shell command with the +poption.cd /custom-root/adapter/libextattr +p *.so

You may also have to define C++ and LE-provided run time libraries, such asSCEERUN, SCEERUN2, SCLBDLL and CSSLIB, to be RACFprogram-controlled.

7. You should redirect the standard output and error streams to the filesstdout.txt and stderr.txt otherwise these files will not automatically becopied to the IBM Support package that is created with the ingxadapter.shIBMSupport command. See also the sample job ING.SINGSAMP(INGXADPT).


||

|||

|||||

||

|||

Start/Stop end-to-end automation adapter

SyntaxYou can start the automation adapter with a USS script that SA z/OS provides:ingadapter.sh function suffix option

This script has the following parameters:

functionThis can be one of the following:

start|STARTThis starts the automation adapter. The default is start.

stop|STOPThis stops the automation adapter.

generateSampleKeysThis creates and stores sample keystore and truststore files in theautomation adapter SSL directory. Both java and keytool must befound in the UNIX PATH environment variable if you want to usethis function.

Note: Use the sample keys for test purposes only.

IBMSupportThis produces a zip file in the data directory of all the necessarylog and trace files that IBM Support might need.

suffix The suffix is optional. It might be used for a shared HFS. The meaning ofsuffix depends on a hyphen "-" as 1st character.1. Suffix that starts WITHOUT a hyphen "-".

The suffix now supports shared HFS environments in a better way.2. Suffix that starts WITH a hypen "-".

In order to support the meaning of the suffix of older releases add ahyphen "-' in front of the suffix.

Suffix starts WITHOUT a hyphen "-".

We refer to output such as end-to-end adapter log files, PID file, stdout,stdin or the adapter release info file. If you want output to be written intoa subdirectory depending on the system name or depending on any othersystem differentiator then use a suffix without a hyphen. This might beuseful for shared HFS. It is treated as the user specified name of thesubdirectory inserted into the data directory path used for output data.Where suffix can be any differentiator for the current system.

For example,ingadapter.sh SYSA

causes the end-to-end adapter to write info into the following outputdirectory/custom-root/adapter/data/SYSA/eez/log

if we assume E2E_CUSTOM_ROOT = /custom-root/adapter/ was set withinconfiguration file ingadapter.properties.

Note, suffix is defined in the JCL parameter and the JCL defines thelocation of stderr and stdout. See example ING.SINGSAMP(INGXADPT).


|

|

|

|||

|

|

|

||

|

|||||||

|

|

||

|

||

||

Suffix starts WITH a hyphen "-".

In this case the suffix (whereby hyphen is removed) is used as middlequalifier for the master configuration file, for example,ing.adapter.suffix.properties

Normally this is no longer needed and should not be used any more. Thisfunction is only supported for compatibility reasons. Example of thecorresponding master configuration files name with suffix SYSAing.adapter.SYSA.properties.

option The parameter option may be used for debugging purposes in order totrace the shell script or debug the end-to-end adapter.

-T, -tswitches on the shell script trace.

-D, -dswitches on the end-to-end adapter logger.

If you want to start in the USS shell, you can use the nohup command to put thestartup in the background, for example:nohup ingadapter.sh start &

Encrypt SSL PasswordThe USS script ingencrypt.sh enables you to encrypt and decrypt any string suchas the SSL password.

In order to invoke the command, ensure that the current working directory is theautomation adapter install-root directory. The java runtime must be installed.

Output is written to stdout.

Example invocation:cd /usr/lpp/ing/adapter./ingencrypt.sh -encrypt abcdef

Command syntaxingencrypt.sh function string

functionThe function to be executed. This can be one of :

-encrypt|-ENCRYPT

-decrypt|-DECRYPT

string The string to be encrypted or decrypted.

JCL Procedure using BPXBATCHThere is a sample procedure, INGXADPT, that is in the SA z/OS samples data setthat allows you to start the automation adapter as a batch job or started task.

You must customize the paths and job statements according to your needs.

To stop the automation adapter use the same procedure with a stop parameter.

It is recommended to define the automation adapter as an application in theautomation policy to operate it with SA z/OS. The goal of these definitions is:

Chapter 8. Operating the end-to-end automation adapter 39

|

||

|

||||

|||

||

||

|||

||

|

|

||

||

||

|

|

||

|

||

|

|

||

v ease of operations supportv availability support reducing downtimesv refer to Chapter 9, “Operating the end-to-end automation adapter via SA z/OS,”

on page 41.

SA z/OS defined resourceDefine the automation adapter as an application in the automation policy tooperate it with SA z/OS.

The goal of these definitions is:v Ease of operations supportv Availability support reducing downtimes

See Chapter 9, “Operating the end-to-end automation adapter via SA z/OS,” onpage 41 for further details.


|

|

||

Chapter 9. Operating the end-to-end automation adapter viaSA z/OS

This information describes how to define the automation adapter as application tobe automated by SA z/OS for simplified operating and high availability.

Automation purpose and rulesThe automation adapter provides the interface between the end-to-end automationmanager and SA z/OS as the first level automation.

It communicates with the local automation agent on the same system, selected asthe primary agent. For synchronous communication it uses theprogram-to-program interface (PPI), for the asynchronous communication path theNetView event/automation service is used.

To optimize the availability of the end-to-end automation infrastructure,automation of the end-to-end automation adapter with SA z/OS can be focusedon:v Automatically restarting failed components that the automation adapter depends

onv Automatically restarting the automation adapterv Failover of a non-recoverable automation adapter to a backup systemv Cleaning up the primary agent after automation adapter has been brokenv Enforcing resynchronization with the end-to-end automation manager if events

have possibly been lost via the asynchronous communication path duringoutages

v Enforcing the recycling of the automation adapter if the primary agent has beenrecycled because of an error situation

Error situations and their resulting automation actions have the following impactsto the automation adapter:v “Non-disruptive recovery from errors”v “Resynchronization of the automation adapter” on page 42v “Recycling the automation adapter in the same system” on page 42v “Restarting the automation adapter or failover to a backup system” on page 42

Non-disruptive recovery from errorsSome error situations can be recovered by SA z/OS without interruption of theautomation adapter.

These error situations are:v A hot restart of the automation manager, when the takeover does not take longer

than two minutes or the time interval provided by the advanced automationoption AOF_E2E_TKOVR_TIMEOUT.

v A short outage of the NetView event/automation service during which noevents failed to be transferred from the primary agent via PPI TECROUTE to themessage adapter of the event/automation service.


The number of send retries can be customized with the advanced automationoption AOF_E2E_EVT_RETRY. The default value is 60 retries at intervals of onesecond.

Resynchronization of the automation adapterIf events to be forwarded to the automation adapter are lost during errorsituations, information about first-level automation resources that is collected bythe end-to-end automation manager cannot be kept up to date.

As long as the asynchronous communication path from the primary agent to theautomation adapter is available despite the error situation, the end-to-endautomation manager is notified about the offline automation domain. As soon asthe end-to-end automation manager is informed that the domain is online again,the end-to-end automation manager has to request initial status information for allresources known by it in the affected automation domain. Such a resynchronizationof the end-to-end automation manager with the first-level automation might causeincreased traffic rate.

Error situations that the automation adapter has to be resynchronized after are:v A stop or abend of the NetView INGPXDST communication taskv A recycle of the automation manager, when the start type is WARM or COLD. In

case of a HOT restart, a resynchronization is only necessary if the outage tooklonger than two minutes or the time interval that is defined with the advancedautomation option AOF_E2E_TKOVR_TIMEOUT.

Recycling the automation adapter in the same systemIf the asynchronous communication path between the automation adapter and theprimary agent is interrupted, the end-to-end automation manager cannot benotified about the error situation via this communication path.

Therefore the automation adapter will be stopped and restarted by SA z/OS afterit has recovered from the error situation.

Furthermore a recycle of the automation adapter is initiated by SA z/OS if theautomation adapter needs to re-initialize the automation domain, for example, aftera recycle of the primary agent.

Error situations that the automation adapter has to be recycled after are:v A restart of the primary agentv A configuration refreshv ACF COLDv An outage of NetView event/automation service, if events have been lostv When the PPI rejects the events that are to be forwarded to the automation

adapter

Restarting the automation adapter or failover to a backupsystem

When the automation adapter stops itself or the appropriate address space fails,resulting in a recoverable status, the automation adapter will be restarted by theautomation as long as the specified critical threshold for the automation adapterhas not been exceeded.


If restart retries are exhausted or the automation adapter terminates indicating anon-recoverable error, the automation initiates a failover to a backup system, if oneis available in the same subplex.

More error situations when the automation adapter has to be moved to a backupsystem are:v If restart retries of the NetView event/automation service are exhaustedv If the NetView PPI is down

Automated applicationsThe automation solution for the end-to-end automation infrastructure considers thefollowing two components to be defined as applications to SA z/OS:v The NetView event/automation servicev The automation adapter

Grouping considerationsTo guarantee that only one automation adapter is running at any given time withina subplex, a MOVE group is defined that contains the automation adapters on thedifferent systems in the subplex.

To prevent a quick move of the automation adapter from one system to another, aMakeavailable/WhenObservedDown relation from the automation adapter to theMOVE group is defined, as shown in Figure 11 on page 44. Thus the automationadapter is not started on a selected system until it is down on all other systemsthat are included in the MOVE group.

Chapter 9. Operating the end-to-end automation adapter via SA z/OS 43

The following abbreviations for relationship types are used:

HP HASPARENT

FD/WOHDFORCEDOWN/WhenObservedHardDown

FD/WODFORCEDOWN/WhenObservedDown

MA/WODMAKEAVAILABLE/WhenObservedDown

Defining automation policyIn the following description of the automation policy definitions, fields of thecustomization dialog where no values have to be specified are not mentioned.

After having customized the automation policy, the BUILD process has to beexecuted to create the control files, and the configuration has to be refreshed withthe INGAMS command.

TCPIP SYSVSSI

E2E_EAS

E2E_ADPT

TCPIP SYSVSSI

E2E_EAS

E2E_ADPT

MA/WOD

E2E_ADPT_X/APG

FD/WOD FD/WOD

HP HP HP HP

HPFD/WOHD

HPFD/WOHD

Figure 11. Sysplex group relationships


Application definition for the NetView event/automationservice (E2E_EAS)

Define an application for the NetView event/automation service for each system inthe sysplex using the description of the policy items in the SA z/OS automationpolicy that follows.

Policy item DESCRIPTIONSpecify an entry name of your choice and a description of the application.

Field name Specified value

Entry Name E2E_EAS

Object Type INSTANCE

Short Description Event Automation Service

Long Description Event Automation Service

Policy item APPLICATION INFOSpecify subsystem name, job name and JCL procedure name of your choice.


Application Type STANDARD

Subsystem Name E2E_EAS

Job Name E2E#EAS

JCL Procedure Name IHSAEVNT

Restart Option * ALWAYS

* This option can be omitted, if the default value has not been changed.

Policy item RELATIONSHIPSDefine HASPARENT relationships from the E2E_EAS to TCP/IP and the NetViewSSI to enforce the right start and stop order, because EAS depends on TCP/IP andthe PPI function of the NetView SSI.


Description E2E_EAS depends on TCPIP

Relationship Type HASPARENT

Supporting Resource TCPIP/APL/=


Description E2E_EAS depends on SYSVSSI


Supporting Resource SYSVSSI/APL/=

Policy item STARTUPThe event/automation service can be started with the default start up command ofSA z/OS for applications. Therefore no definitions to this policy item are needed.


Policy item SHUTDOWNSpecify shutdown commands for shutdown phase NORM.

Pass Automated Function/* Command text

1 MVS P &SUBSJOB

4 MVS C &SUBSJOB

The shutdown command to PASS1 causes the E2E#EAS job to halt all activity andend normally. The shutdown command to PASS4 ends the started taskimmediately.

Policy item THRESHOLDSSpecify a critical threshold to limit the number of times that the restart in the samesystem of the event/automation service is attempted. The critical threshold has tobe specified as the number of times the error must occur within a certain timeinterval.

Policy item WHERE USEDSelect an appropriate basic group, with or without an automation name, to link theapplication to all the systems in the sysplex.

Application definition for the end-to-end automation adapter(E2E_ADPT)

Define an application for the automation adapter for each system in the sysplexusing the description of the policy items in the SA z/OS automation policy thatfollows.

Policy item DESCRIPTIONSpecify an entry name of your choice and a description of the application.


Entry Name E2E_ADPT

Object Type INSTANCE

Short Description E2E Automation Adapter

Long Description E2E Automation Adapter

Policy item APPLICATION INFODefine the automation adapter as an application of job type MVS to be started by aprocedure. Specify subsystem name, job name and JCL procedure name of yourchoice.


Application Type STANDARD

Subsystem Name E2E_ADPT

Job Name E2E#ADPT

JCL Procedure Name INGXADPT

Start Timeout 00:05:00

Restart Option * ALWAYS

* This option can be omitted, if the default value has not been changed.


If the parameter eez-initial-contact in the master configuration file of theautomation adapter is set to true, so that the automation adapter tries to establishinitial contact with the end-to-end automation server during startup, specify avalue for Start Timeout that is consistent with the parameter eez-initial-contact-retry-interval-minutes in the master configuration file of the automation adapter.

Start Timeout less than eez-initial-contact-retry-interval-minutes:Specify a value for Start Timeout that is less than parameter eez-initial-contact-retry-interval-minutes. The agent status of the automation adapter changes toSTARTED2 after the Start Timeout has elapsed while the automation adapter wasstill trying to establish initial contact with the end-to-end automation server.

As soon as contact is acknowledged by the end-to-end automation server and theautomation adapter successfully completes its initialization, the status changes toUP.

If no contact can be established within the time that is set in eez-initial-contact-retry-interval-minutes, the automation adapter stops itself and will be restarted bySA z/OS as long as the critical threshold for failed restarts has not yet beenexceeded.

The advantage of specifying a Start Timeout value less than eez-initial-contact-retry-interval-minutes is to indicate that there is a problem when the specified StartTimeout interval to establish the initial contact has nearly elapsed.

Start Timeout greater then eez-initial-contact-retry-interval-minutes:If the value for Start Timeout is greater than parameter eez-initial-contact-retry-interval-minutes, the automation adapter might stop before the agent status hasindicated a problem.

Policy item RELATIONSHIPSDefine relationships starting from the automation adapter to different supportingresources.

The HASPARENT relationship from the automation adapter to E2E_EAS enforcesthe right start or stop order, because the automation adapter depends on the EASmessage adapter service.


Description Automation Adapter depends on E2E_EAS


Supporting Resource E2E_EAS/APL/=

The FORCEDOWN relationship from the automation adapter to E2E_EAS enforcesa shutdown of the automation adapter if the EAS resource fails and cannot berestarted on the same system.


Description Force down adapter when E2E_EAS isharddown

Relationship Type FORCEDOWN

Supporting Resource E2E_EAS/APL/=

Condition WhenObservedHardDown


The FORCEDOWN relationship from the automation adapter to the NetView SSIenforces a shutdown of the automation adapter when the NetView SSI stops,because the communication between the automation adapter and the primaryagent depends on the PPI of the NetView SSI.


Description Force down adapter when SYSVSSI is down

Relationship Type FORCEDOWN

Supporting Resource SYSVSSI/APL/=

Condition WhenObservedDown

The MAKEAVAILABLE relationship from the automation adapter to the MOVEgroup prevents a quick move of the automation adapter. It makes sure that theautomation adapter is not started on any system in the sysplex until it is down onall systems in the sysplex.


Description Prevent quick move of adapter

Relationship Type MAKEAVAILABLE

Supporting Resource E2E_ADPT_X/APG

Condition WhenObservedDown

Policy item MESSAGES/USERDATAThe automation adapter manages a plug-in for z/OS that is started and stopped bythe automation adapter. It runs in the same address space as the automationadapter and issues its own messages.

During a successful startup of the automation adapter the following messages areissued, indicating the progress of the startup.▌1▐ S INGXADPT,JOBNAME=ADAPTER,F=START

IEF695I START INGXADPT WITH JOBNAME E2E#ADPT IS ASSIGNED TO USER STCUSER ,GROUP STCGROUP$HASP373 E2E#ADPT STARTED

▌2▐ IEF403I E2E#ADPT - STARTED - TIME=17.23.34$HASP373 BPXAS STARTEDIEF403I BPXAS - STARTED - TIME=17.23.35

▌3▐ EEZA0100I The adapter has been started▌4▐ EEZA0056I Initial contact was enabled and the connection to the management

server has been established▌5▐ EEZA0101I The adapter is active

EEZA0111I The plug-in is starting: class com.ibm.ing.sam.INGXPluginINGX9802I INGXLogger has successfully been initialized using configurationfile ing.adapter.jlog.properties from path /u/aoc/310/instance/config.INGX9902I INGXPluginLogger has successfully been initialized using configurationfile ing.adapter.jlog.properties from path /u/aoc/310/instance/config.

▌6▐ EEZA0112I The plug-in has been started: class com.ibm.ing.sam.INGXPlugin▌7▐ EEZA0102I The adapter is ready

▌1▐The start command for the end-to-end automation adapter.

▌2▐Message IEF403I is used to change the agent status of the automation adapterto ACTIVE.


▌3▐The first message that is issued by the automation adapter is also used tochange the agent status of the automation adapter to ACTIVE.

▌4▐If the eez-initial-contact parameter in the automation adapter masterconfiguration file is set to true, the automation adapter tries to establish initialcontact with the end-to-end automation server after it has issued the previousmessage EEZA0100I. Message EEZA0056I informs that the connection has beenestablished successfully.

▌5▐The automation adapter has successfully established the connection to themanagement server and now continues initialization by starting the plug-in.

▌6▐Message EEZA0112I indicates that the plug-in has successfully initialized thedomain. It is used to change the agent status of the automation adapter to UP.

▌7▐Message EEZA0102I indicates that the automation adapter startup sequence iscomplete.

If the startup of the automation adapter or the plug-in fails, the automationadapter stops after having issued an error message. SA z/OS has to be toldwhether the error message indicates a recoverable abnormal end of the application,so that the automation will try to restart the application. The status BROKENindicates a non-recoverable abend and automation will not try to restart theautomation adapter.

During a failed startup of the automation adapter the following messages may beissued, for example:▌1▐ S INGXADPT,JOBNAME=E2E#ADPT,F=START

$HASP100 E2E#ADPT ON STCINRDRIEF695I START INGXADPT WITH JOBNAME E2E#ADPT IS ASSIGNED TO USER STCUSER ,GROUP STCGROUP$HASP373 E2E#ADPT STARTED

▌2▐ IEF403I E2E#ADPT - STARTED - TIME=19.26.31▌3▐ EEZA0100I The adapter has been started▌4▐ EEZA0057E The connection to the management server cannot be established▌5▐ EEZA0103I The adapter is stopping▌6▐ EEZA0105I The adapter has been stopped due to a failure, rc=12

AOF571I 19:26:56 : ADAPTER SUBSYSTEM STATUS FOR JOB ADAPTER IS ABENDING - SUBSYSTEMHAS SUFFERED A RECOVERABLE ERROR

▌7▐ IEF404I ADAPTER - ENDED - TIME=19.26.56$HASP395 ADAPTER ENDED

▌1▐The start command for the automation adapter.

▌2▐Message IEF403I is used to change the agent status of the automation adapterto ACTIVE.

▌3▐The first message that is issued by the automation adapter is also used tochange the agent status of the automation adapter to ACTIVE.

▌4▐If the eez-initial-contact parameter in the automation adapter masterconfiguration file is set to true, the automation adapter tries to establish initialcontact with the end-to-end automation server after having issued message


EEZA0100I. Message EEZA0057E informs about the elapsed timeout intervalthat is provided to establish initial contact with the end-to-end automationserver

▌5▐The automation adapter stops itself. Message EEZA0103I is used as a statusmessage to change the status of the automation adapter to TERMINATING.

▌6▐Message EEZA0105I indicates the error situation and is used to change thestatus of the automation adapter to ABENDED.

▌7▐Message IEF404I is used as the final termination message.

Defining status messages:The automation table provided by SA z/OS already includes statements for statusupdates that are based on the following messages that are issued by theautomation adapter during startup or shutdown processing and in error situations.

Message ID Status

EEZA0032E BROKEN

EEZA0100I ACTIVE

EEZA0103I TERMINATING

EEZA0104I TERMINATED

EEZA0105I ABENDED

EEZA0112I UP

EEZA0115I BREAKING

If you do not use easy message management for the automated build of theautomation table based on these definitions, additional statements have to bespecified in your automation table to call the generic routines ACTIVMSG andTERMMSG with the appropriate parameters to update the resource status.

Defining messages to be captured:Messages that are issued by an application can be captured for subsequent displaywith the DISPINFO command. Capturing the messages that are issued by theautomation adapter helps in analyzing problems with the automation adapter.

To define messages to be captured, enter the message IDs and select Capture afterhaving entered action AUTO.

Useful messages in analyzing problems are:v EEZA0037Ev EEZA0038Ev EEZA0055Ev EEZA0056Iv EEZA0057Ev EEZA0061Ev EEZA0101Iv EEZA0102Iv EEZA0111I


v EEZA0113Iv EEZA0114Iv EEZA9991Ev EEZA9992Ev INGX9705Ev INGX9707Iv INGX9709Ev INGX9711E

If you do not use easy message management for the automated build of theautomation table based on these definitions, additional statements have to bespecified in your automation table to call the generic routine AOFCPMSG tocapture these messages.

Defining commands:Define the following commands to be executed in response to messages IEF404Iand IEF450I or in certain situations.

Enter the message ID and specify the command after having entered CMD as theaction.

Message ID Pass/SelectionAutomatedFunction/'*' Command Text

IEF404I INGE2E RESET

IEF450I INGE2E RESET

The command for messages IEF404I and IEF450I cleans up the primary agent toenable a new automation adapter initialization.

Defining code processing:The following code processing definition adjusts the severity of captured messages.

Messages that indicate normal status changes during startup and shutdown aredisplayed with severity NORMAL, others with severity UNUSUAL.

Enter the message ID CAPMSGS and specify the codes and values after havingentered action CODE.


Message ID Code 1 Code 2 Code 3 Value Returned

CAPMSGS EEZA0037EEEZA0038EEEZA0055EEEZA0057EEEZA0061EEEZA9991EEEZA9992EIEF450IINGX9705EINGX9707IINGX9709EINGX9711EEEZA0056IEEZA0101IEEZA0102IEEZA0111IEEZA0113IEEZA0114I

******************

******************

UNUSUALUNUSUALUNUSUALUNUSUALUNUSUALUNUSUALUNUSUALUNUSUALUNUSUALUNUSUALUNUSUALUNUSUALNORMALNORMALNORMALNORMALNORMALNORMAL

Policy item STARTUPThe sample procedure INGXADPT that is provided to start the automation adapteruses the value of parameter F to decide whether to start or stop the automationadapter with the same procedure. You must therefore specify parameter F as anadditional parameter for the default startup command. If you have customized thesample procedure to accept further parameters, append them to this list.

Parameter Value

Startup Parameters ,F=START,SX=&SYSNAME

The SX parameter is optional and might be needed if the system name has to bepassed as a suffix parameter to the USS script ingadapter.sh.

Policy Item REFRESHSTART

Specify the refreshstart command to enforce a recycle of the MOVE group whichresults in a recycle of automation adapter on the same system after:v A recycle of the primary agentv A configuration refresh

For the refreshstart command specify:

Auto/Fn* Command Text

INGE2E RECYCLE E2E_ADPT_X/APG

Policy item SHUTDOWNSpecify shutdown commands for the different shutdown phases.

The start procedure of the automation adapter is also used to stop the automationadapter. To prevent confusing start or stop messages of the procedure whenstopping the automation adapter, specify a different job name. If you havecustomized the sample procedure to accept further parameters, append them to theSTART command of the procedure.


For shutdown phase NORM specify:


1 MVS S &SUBSPROC,JOBNAME=ADPTSTOP,F=STOP

4 MVS C &SUBSJOB

For shutdown phase IMMED specify:


1 MVS S &SUBSPROC,JOBNAME=ADPTSTOP,F=STOP

2 MVS C &SUBSJOB

For shutdown phase FORCE specify:


1 MVS C &SUBSJOB

Policy item THRESHOLDSSpecify a critical threshold to limit the number of times that the restart in the samesystem of the automation adapter is attempted. The critical threshold has to bespecified as the number of times the error must occur within a certain timeinterval.

Policy item WHERE USEDSelect the sysplex group E2E_ADPT_X/APG.

MOVE group for the automation adapters (E2E_ADPT_X)Define an application group for the automation adapters on the different systemsin the sysplex according to the following description.

Policy item DESCRIPTIONSpecify an entry name of your choice and a description of the MOVE group.


Entry Name E2E_ADPT_X

Short Description MOVE group for E2E Automation Adapter

Long Description MOVE group for E2E Automation Adapter

Policy item APPLGROUP INFODefine the application group as MOVE group belonging to a sysplex.


Application Group Type SYSPLEX

Nature MOVE

Default Preference *DEF

Automation Name E2E_ADPT_X

Behaviour ACTIVE


Policy item APPLICATIONSSelect E2E_ADPT as application members for the group.

Policy item RESOURCESThe default initial preference values can be taken unchanged.

Policy item WHERE USEDSelect the sysplex to link the MOVE group.

Limitations to the automation1. If the EAS message adapter is stopped separately with the command F

E2E#EAS,STOP TASK=MESSAGEA, events might be lost unnoticed by theautomation because EAS still receives incoming events and discards them.To prevent losing events in this way, always stop the message adapter bystopping E2E_EAS. The automation then notices the outage and tries to makethe E2E_EAS application available again by restarting it in the same system orby moving it together with the automation adapter to a backup system.

2. No actions are taken when NetView is stopped on the primary agent, becauseit is assumed that NetView is usually down only for a short time. Thus theautomation adapter does not have to be moved to another system.If a longer outage of NetView is planned, the automation adapter has to bemoved manually to another system in the sysplex before NetView is stopped.


Chapter 10. Problem determination

This information describes methods for determining and solving various problemsthat you might encounter. It includes descriptions of methods to analyze:v “Problems with selecting the primary agent” on page 56v “Problems with the program-to-program interface” on page 56v “Problems with NetView event/automation service” on page 56v “Problems with consumer registration” on page 57v “Link list errors” on page 58v “TCP/IP bind socket problem” on page 58v “Timeout problems” on page 59v “USS problems” on page 59v “CHECK_HEALTH function failure” on page 60v “Automation domain remaining offline after error recovery” on page 60

Diagnosis of the SA z/OS tasks for the adapterUse command DISPAOPS if initialization of the domain fails (and messageAOF233E is issued) to check the existence and status of the automated operatorfunction EVTOPER.

Output is similar to that shown in Figure 12.

End-to-end automation adapter diagnosis commandsIf necessary, you can switch on or off automation adapter trace using the followingcommands:INGE2E SETDBGLVL NORMALINGE2E SETDBGLVL NORMAL,EXP,SEC,APIINGE2E DELDBGLVL ALL

If necessary, you can collect debug information using the following command:INGE2E DEBUG SIZE=LONG EAS=eas_jobname TCPIP=tcp_jobname

The debug information that is collected is written to DSILIST(INGE2E00).

AOFK2SO SA z/OS - Command Dialogs Line 1 of 33Domain ID = IPSNP ---------- DISPAOPS ---------- Date = 11/25/04Operator ID = OPER1 Time = 11:08:30

AutomatedSystem Function Primary Status Secondary Status-------- ---------- ------- ------ --------- ------KEY4 EVTOPER AUTEVT1 ACTIV AUTEVT2 ACTIVKEY4 E2EOPER AUTE2E ACTIVKEY4 E2EOPR01 AUTE2E01 ACTIVKEY4 E2EOPR02 AUTE2E02 ACTIVKEY4 E2EOPR03 AUTE2E03 ACTIV

Command ===>PF1=Help PF2=End PF3=Return PF6=Roll

PF8=Forward PF9=Refresh PF12=Retrieve

Figure 12. DISPAOPS command response


If you do not specify the EAS parameter, EAS information is not retrieved.

If you do not specify the TCPIP parameter, it is taken fromCNMSTYLE.TCPNAME

Problems with selecting the primary agent

To check whether the NetView agent has been selected as the primary agent towork with the automation adapter, enter the INGAMS command to display theprimary agent flag, as shown in Figure 13. The value YES in the last columnindicates that the primary agent flag has been set for the agent.

Problems with the program-to-program interfaceTo display status and buffer queue information for a PPI receiver, use the NetViewcommand:DISPPI ALL|RCVRID=receiver_id

or, from an MVS console:MODIFY ssiname,DISPPI ALL|RCVRID=receiver_id

where ssiname specifies the MVS subsystem interface name and receiver_id the PPIreceiver ID.

Problems with NetView event/automation serviceTo display operational characteristics of the event/automation service, use theMVS command:MODIFY procname,DISPLAY,STATUS|QSTATS

The STATUS option displays information about:v The operational status of each service

INGKYAM0 SA z/OS - Command Dialogs Line 1 of 2Domain ID = IPSNP ---------- INGAMS ---------- Date = 10/01/04Operator ID = OPER1 Sysplex = KEY1PLEX Time = 17:01:49

Cmd: A Manage B Show Details C Refresh Configuration D Diagnostic

Cmd System Member Role Status Sysplex XCF-Group Release Comm--- -------- --------- ----- ---------- -------- --------- ------- ----

KEY4 KEY4$$$$3 PAM READY KEY1PLEX INGXSG34 V2R4M0 XCFKEY4 KEY4 AGENT READY KEY1PLEX INGXSG34 V2R4M0 XCF YES

Command ===>PF1=Help PF2=End PF3=Return PF6=Roll

PF9=Refresh PF12=Retrieve

Figure 13. INGAMS command dialog panel


v The connectivity of the service outside of the event/automation service addressspace via PPI and TCP/IP

The QSTATS option displays information about the number of data buffers sentand received by all of the subtasks that make up the event/automation service,and the total number of data buffers that are currently queued to a subtask andthat have not been processed.

To display the configuration parameter of the NetView message adapter, use theMVS command:MVS F NETEVE2E,SETTINGS,TASK=MESSAGEA

For more details concerning the information that is displayed see Tivoli for z/OSCommand Reference Vol. 1.

Examples1. At the NetView console entering:

MVS F NETEVE2E,DISPLAY,STATUS

displays information as shown in Figure 14.

2. At the NetView console entering:MVS F NETEVE2E,DISPLAY,QSTATS

displays information as shown in Figure 15. You can use this to find out wherethe event flow has broken down.

Problems with consumer registrationIn order to be receive events, end-to-end automation has to register as an eventconsumer.

To check whether the end-to-end automation was correctly registered atinitialization, use the following command:INGEVOBS LIST

IHS0141I SERVICE STATUS ADDITIONAL INFOIHS0142I ------- ------ ---------------IHS0143I ALERTA DOWN connection idleIHS0143I MESSAGEA UP *IHS0143I EVENTRCV DOWN *IHS0143I TRAPALRT DOWN *IHS0143I ALRTTRAP DOWN *IHS0143I PPI UP INGEVE2EIHS0143I TCP/IP UP 9.152.87.64

Figure 14. Event/automation service STATUS information

IHS0145I TASK QCOUNT TOTAL SENT TOTAL RCVDIHS0146I ---- ------ ---------- ----------IHS0147I CONTROL 0 23 0IHS0147I ALERTA 0 23 0IHS0147I MESSAGEA 0 0 23IHS0147I EVENTRCV 0 0 0IHS0147I TRAPALRT 0 0 0IHS0147I ALRTTRAP 0 0 0

Figure 15. Event/automation service QSTATS information

Chapter 10. Problem determination 57

The output should be as shown in Figure 16.

It should list E2E as an event consumer and display the clist INGRTECS as theexit. The User data column shows the PPI receiver ID that has been defined for theevent/automation service. The default value is INGEVE2E and you can change itwith the advanced automation option AOF_E2E_EAS_PPI before starting theautomation adapter. For details see “SA z/OS advanced automation options” onpage 20.

Link list errorsBefore running the automation adapter make sure that the link list contains thenecessary libraries.

Use the command:D PROG,LNKLST

and check the existence of the following libraries:SYS1.SCLBDLL2SYS1.SCEERUNSYS1.SCEERUN2SYS1.SCLBDLLhlq.SINGMOD1

Otherwise you might get an error similar to the following:CEE3501S The module INGIOC was not found.

From entry point __dllstaticinit at compile unit offset +000005EEat entry offset +000005EE at address 2C936316

Alternatively, edit the ingadapter.sh start script and add these libraries as follows:export STEPLIB=SYS1.SCLBDLL2:SYS1.SCEERUN:SYS1.SCEERUN2:SYS1.SCLBDLL:hlq.SINGMOD1:$STEPLIB

TCP/IP bind socket problemAfter stopping the automation adapter, if you then restart it immediately, youmight receive a message similar to the following (note that the port number iscustomizable):EEZA0061E Unable to bind a socket to address BOEKEY4 at port 2001.

Reason: EDC8115I Address already in use.

Although the connection has automatically been freed by TCP/IP, this occursbecause the end-to-end automation server has not yet closed the socket to theterminated automation adapter.

To drop the connection:1. Enter the TSO command NETSTAT (PO nnnn) to list connections for port nnnn,

for example:

Consumer Events Exit AUTOOPER User data---------------- -------- -------- -------- ------------------------E2E 1,2 INGRTECS INGEVE2E*** End of Display ***

Figure 16. INGEVOBS LIST command response


EZZ2350I MVS TCP/IP NETSTAT CS V1R5 TCPIP Name: TCPIP 16:29:23EZZ2585I User Id Conn Local Socket Foreign Socket StateEZZ2586I ------- ---- ------------ -------------- -----EZZ2587I CU11ADAP 0000D0B2 9.152.87.64..2001 9.152.172.117..1365 FinWait2

2. Enter the TSO command:TSO NETSTAT,DROP CONNID

where CONNID is the connection ID in the column Conn. For example, thecommand TSO NETSTAT,DROP 0000D0B2 should produce the following output:EZZ2622I Connection successfully dropped

Timeout problemsTimeout problems may occur at the operations console if you display resource databy selecting an SA z/OS domain in the topology tree and navigating through theresource tree.

The data that is displayed has to be requested from the automation adapter. Theseend-to-end automation requests are mapped to SA z/OS commands that query therequested data from the automation manager. Before sending the query commandsto the automation manager, the primary automation agent checks the expirationtime for the end-to-end automation requests. If the expiration time that remains istoo short, the requested command is rejected, resulting in error message ING249Ethat indicates that a task execution request timed out.

The expiration time of an end-to-end automation request is determined by where itis issued, as follows:

Request issued from: Expiration time determined by:

The GUI or the end-to-endautomation manager

The timeout interval that is defined in the end-to-endautomation server's WebSphere Admin Console for theenvironment variable com.ibm.eez.aab.invocation-timeout-seconds

The automation adapter (suchas INIT_DOMAIN)

The timeout interval that is defined in the automationadapter ing.adapter.plugin.properties configuration file

It is possible that an end-to-end automation request that has been issued might bequeued in the automation adapter or the NetView operator task for a certainperiod of time. You should therefore make the timeout interval large enough totake this delay into account.

For details about the relationship between the expiration time and the WAITparameter of SA z/OS commands, see The WAIT Parameter.

USS problemsTo avoid problems with loading DLLs in shared memory, it is recommended thatyou always have the Java Just-In-Time (JIT) compiler enabled. That is, you shouldnever set (or always leave unset) the JAVA_COMPILER environment variable.

Chapter 10. Problem determination 59

USS Shared File SystemIf the USS File System is shared between the systems where the automationadapter might be moved from and to, then the old and the new automationadapters write into the same files stdout.txt and stderr.txt.

This might result in truncated output lines.

You can avoid this by using the parameter suffix in the automation adapter startcommand, for example,ingadapter.sh start SYS1

Refer to Chapter 8, “Operating the end-to-end automation adapter,” on page 37.

CHECK_HEALTH function failureWhen you stop NetView or the SSI Subsystem you should recycle the automationadapter.

See the description of REFRESHSTART in “Policy item STARTUP” on page 52.

If you do not recycle the automation adapter, any CheckHealth command that isperiodically received from the end-to-end automation server will result in errormessages INGX9905 and INGX9820. This may cause many error messages to bewritten to the SYSLOG.

Automation domain remaining offline after error recoveryWhen restarting the automation manager or the INGPXDST communication task,during which the asynchronous communication path from the primary agent to theautomation adapter is still available, the end-to-end automation manager isnotified about the offline automation domain.

If there are problems notifying the end-to-end automation manager about therecovered error situation, the domain may remain offline rather than becomeonline.

When creating the ready event for the end-to-end automation manager, requestssent to the automation manager may time out. In this case the ready event is notsent and the adapter online event is also not sent to the end-to-end automationmanager.

By default, the primary agent waits 90 seconds for the response. A longer timeoutinterval can be provided in the common global variable INGREQ_WAIT.

The following error messages relating to these timeouts are written to theNETLOG:ING008I INGPYAMC SERVICE FAILED, RC=2 - REASON=TIMEOUT MOD=INGRYEVT - GET_QUAL_RESOURCE_RELS (INGEVOBS)ING235W No information from automation manager. READY event not created for E2E.ING276E Execution of a service timed out.

The command INGE2E RESYNC can also be used to notify the end-to-endautomation manager about the recovered error situation.


Appendix A. Configuration file parameters

The following tables provide details about all of the configuration file parameters.

Table 5. Master configuration file (ing.adapter.properties) parameters. In alphabetical order.

Parameter Name Default Description

eez-initial-contact 1 false Value: true or false.

If this parameter is set to true, the automation adapter tries toestablish initial contact with the end-to-end automationmanagement server.

eez-initial-contact-retry-interval-minutes 1

0 min Value range: 0, 1, ..., 1440 minutes.

Zero (0) means never ending. Otherwise the automationadapter stops after the specified number of minutes. Theautomation adapter attempts to send an AdapterJoinEvent tothe server every minute.

If the end-to-end automation management server respondswith an acknowledgement request, the automation adaptercontinues with normal initialization.

eez-max-connections 3 Value range: 1 through 10.

The number of concurrent working threads. Ideally, thisshould be the same as the number of NetView end-to-endautomation tasks.

eez-operator-authentication true Value: true or false.

If this is set to false, the automation adapter uses theSA z/OS-provided JAAS default login module for operatorID and password validation. That is, the following entry inthe adapter JAAS configuration file,ing.adapter.jaas.properties, is used:

EEZAdapterDefaultLogin {com.ibm.eez.adapter.EEZAdapterDefaultLoginModule

required ;};

However, if this parameter is set to true, the automationadapter uses the RACF-provided user ID checking routine.That is, the following entry in the adapter JAAS configurationfile is used:

EEZAdapterLogin {com.ibm.security.auth.module.OS390LoginModule

required;};

eez-plugin-classpath 1 none An optional security feature. It specifies the directories thatare used to load the backend and the plug-in Java classes.

If specified, the plug-in is not loaded from the standardCLASSPATH.

If not specified, the classes are loaded from the standardCLASSPATH.

All other classes are loaded from the standard CLASSPATH.


|||

|||

Table 5. Master configuration file (ing.adapter.properties) parameters (continued). In alphabetical order.


eez-remote-contact-activity-interval-seconds 1

400 sec Value range: 0, 1, ..., max

Setting this parameter to 0 means it never expires. maxindicates the maximum interval that can be defined in Java.

The threshold that the automation adapter is stopped at if asynchronous request (including CHECK_HEALTH) is notreceived. Verification is triggered by an asynchronousreceived event.

eez-remote-contact-hostname automatically The host name or IP address that is used by the automationadapter to receive synchronous requests from the E2Emanagement server. Specify hostname for a VIPAenvironment or if the hostname cannot automatically bedetected. Default is the hostname which is detectedautomatically by the command hostname.

eez-remote-contact-over-ssl false Value: true or false.

The automation adapter uses SSL (true) or plain (false) socketconnection for remote contact to the end-to-end automationserver.

eez-remote-contact-port none Value range: 1 through 65535

The port that belongs to the host name that is defined ineez-remote-contact-hostname.

eez-stop-delay 1 5 sec Value range: 3 through 60 seconds.

Setting this parameter delays the stopping of the automationadapter for the specified number of seconds. This gives theadapter time to deliver the leave event properly.

eif-cache false Value: true or false.

Switch EIF caching on (true) or off (false).

eif-cache-size 500 Value: 1, 2, ...

The maximum number of events that are cached if the eventcannot be delivered. This parameter is only used ifeif-cache=true.

eif-receive-from-hostname none The host name to be used by the automation adapter toreceive EIF events. It must fit the naming convention of theoriginal EIF ServerLocation parameter.

eif-receive-from-port 5529 The port that is to be used by the automation adapter toreceive EIF events. It must fit the naming convention of theoriginal EIF ServerPort parameter.

eif-retry-interval-seconds 30 sec Value: 1, 2, ...

The number of seconds until a disconnected EIF socket willattempt to reconnect.

eif-send-to-hostnameE2Eserver_host

The host name that is to be used by the automation adapterto send EIF events. It must fit the naming convention of theoriginal EIF ServerLocation parameter.

eif-send-to-port none The port that is to be used by the automation adapter to sendEIF events. It must fit the naming convention of the EIFServerPort parameter.

plugin-configfile-sa4zos none The name of the plug-in configuration file.


||||||||

Table 5. Master configuration file (ing.adapter.properties) parameters (continued). In alphabetical order.


1 These parameters are not specified in the sample master configuration file that is supplied.

Note: Table 6 lists only those parameters that you can update.

Table 6. Plug-in configuration file (ing.adapter.plugin.properties) parameters


GRPID None This is a 2-character group ID. It must be equal to the group ID ofthe corresponding SA z/OS XCF group. See DSIPARM(INGXINIT).

PPIBQL 3000 Value: positive number

The PPI buffer queue limit for the PPI queue that is used by eachconnection.

The number of elements in the PPI queue—this indicates how largethe response to a request may be. It should be greater than thenumber of queue elements that you expect to be returned.

AUTOPFN None Value: 8-character string

This a NetView operator task name or an SA z/OS automatedfunction name to be used by SA z/OS to execute the incomingautomation adapter request.

TIMEOUT 600 Value: positive number

Timeout in seconds that is used when initializing or stopping thedomain and for any incoming request that has no timeout value ofits own.

TIMEOUT_SA_NOTAVAIL 0 Value: positive number or zero

Timeout value in seconds. A number greater than zero causes theplug-in to terminate if, after the time period that is specified, itdetects that the SA z/OS NetView Agent is no longer available.

The timeout is initially set to 180 seconds.

CODEPAGE Cp1047 Value range: See Java code page definition.

The code page that is used to convert Java strings to EBCDIC. Thisapplies to SA z/OS resource name, owner field, comment field,and so on. The name of the code page must match the code pagenames supported by java.io See for example http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html.

AUDITMSG true If parameter AUDITMSG was set to true then requests sent by themanagement server and received by the automation adapter will belogged within the message file msgAdapter.log andmsgFlatAdapter.log. If parameter AUDITMSG was set to false theseinformation messages are not logged.

Appendix A. Configuration file parameters 63

|||||||

http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html

http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html

Table 6. Plug-in configuration file (ing.adapter.plugin.properties) parameters (continued)


plugin-domain-name ?Domain Value: string up to 64 characters

This is the name of the SA z/OS domain as it appears in theend-to-end automation operations console. In end-to-endautomation, a SA z/OS domain is defined as a group of SA z/OSagents and managers that belong to the same XCF group ID(GRPID).

All domains known by end-to-end automation must be unique.This includes domains that are defined within a sysplex as well asdomains defined within UNIX clusters using System Automationfor Application Manager.

If the parameter is omitted or the name begins with a ? the plug-ingenerates a name that consists of the sysplex name and theINGXSG where nn is the XCF group id GRPID.

You can however pursue your own naming strategy.

Table 7. SSL configuration file (ing.adapter.ssl.properties) parameters

Parameter Name Description

eez-ssl-truststore The name of the truststore file that is used for SSL (optional).

If omitted the truststore is used from the Java property-Djavax.net.ssl.trustStore

eez-ssl-keystore The name of the keystore file that is used for SSL (optional).

If omitted the keystore is used from the Java property-Djavax.net.ssl.keyStore

eez-ssl-keystorepassword The password of the keystore file. It is required if the keystore file wasspecified.

If omitted the keystore is used from the Java property-Djavax.net.ssl.keyStorePassword

eez-ssl-keystorealias The alias name of the certificate to be used by the server. If this is notspecified the keystore file must contain only one entry, which is the one tobe used. See Chapter 7, “Security,” on page 33.


|||

|||||

||||

|||

|

Appendix B. SA z/OS specific implementation of theend-to-end automation resource data model

This information describes the SA z/OS specific implementation of the end-to-endautomation resource data model.

Resource data displayed by the WebUIThis section describes the information that is displayed by the WebUI.

Automation Domains

It shows the name of the automation domains and its systems. For an SA z/OSdomain the systems are those that have been defined in the automation policy andlinked to the sysplex group. The sysplex group is represented by the XCF groupname INGXSGnn where nn is the corresponding group id.

The following elements of the operations console are described:v “Domain object”v “Node object” on page 67v “Resource object” on page 67

Domain objectA domain object shows general information for an automation domain.

Domain stateOnline

SA z/OS is ready for automation.Offline

SA z/OS is inhibited from automating resources or events are lost.The following are examples of error situations:v The NetView task INGPXDST has stoppedv The automation manager has stopped within either at least 2

minutes or the time interval that is provided by the advancedautomation option AOF_E2E_TKOVR_TIMEOUT.

UnknownThe automation adapter is not running.

Policy database nameThe name of the automation policy database.

Policy file nameThe name of the automation policy database file (ACF file name) that iscurrently loaded by the automation manager. An AM cold or warm start,or a refresh might change this domain attribute.

Activation dateThe date of the last refresh of the automation configuration as provided bythe automation manager. If the configuration has not yet been refreshed,the start date of the automation manager is shown.


|

|

|

||||

|

|

|

|

|

|

||||||||||||

||

||||

||||

Activation timeThe time of the last refresh of the automation configuration. If theconfiguration has not yet been refreshed, the start time of the automationmanager is shown.

The domain object has additional properties such as:

Product nameThe product name of System Automation for z/OS.

VersionThe version of System Automation for z/OS.

Adapter nameThe name of the automation adapter.

VersionThe version of the automation adapter.

Node The identifier for the system where the automation adapter is running.This is the host name as defined with the eez-remote-contact-hostnameparameter in the automation adapter configuration file,ing.adapter.properties.

Primary Manager StartTypeThe start type of the automation manager. Possible values are COLD,WARM, and HOT.

Primary Manager NameThe name of the primary automation manager, as shown by the primaryagent via the INGAMS command.

XCF Group NameThe name of the XCF group that is associated with the automationmanager and primary agent.

Sysplex NameThe name of the sysplex that the primary agent is located in.

Primary Agent VersionThe SA z/OS version of the primary agent.

Primary Agent NameThe name of the primary agent, as shown by the primary agent via theINGAMS command.

Primary Agent NetView VersionThe NetView version of the primary agent.

Adapter Operating SystemThe operating system that the automation adapter is running in.

Adapter Java Runtime VersionThe Java run time version that the automation adapter is running in.

Adapter Startup TimeThe timestamp when the automation adapter was started.

Adapter Plugin Startup TimeThe timestamp when the automation adapter plug-in was initialized.

Adapter Plugin Build VersionA unique identifier that defines the version of the automation adapterplug-in and when it was built.


||||

|

||

||

||

||

|||||

|||

|||

|||

||

||

|||

||

||

||

||

||

|||

Primary Manager Startup TimeThe start time of the primary automation manager.

Primary Manager System NameThe z/OS system name that the automation manager is running on.

Node objectA node object is a z/OS system:

Name The name of the system.

Class The resource type of the system.

DescriptionThe description as specified as the short description in the DESCRIPTIONpolicy item of the automation policy.

Observed stateOffline if the observed state of this resource as detected by SA z/OS isSYSGONE; otherwise Online.

Is included/excluded in automationExcluded if there is a stop request to the resource system/SYG/system;otherwise included.

Include/Exclude nodeThe automation adapter converts these functions to the SA z/OS specificcommand. For details of these requests see “Requests issued by theoperations console and the end-to-end automation manager” on page 69.

Resource objectThe resource object has properties such as:

Name The resource name consisting of name, type and optionally system.

Class The resource type.

Automation domainThe name of the automation domain. If it is not specified in theplugin-domain-name parameter of the automation adapter plug-inconfiguration file, it is automatically generated as the concatenation of thesysplex name and the XCF group name.

Node The z/OS system name.

OwnerThe owner as specified in the AUTOMATION INFO policy item of theautomation policy.

Info linkThe Info link as specified in the AUTOMATION INFO policy item of theautomation policy.

DescriptionThe description as specified as the short description in the DESCRIPTIONpolicy item of the automation policy. Due to translation between UTF-8and the EBCDIC code page, some characters might be lost. See also theCODEPAGE parameter in “The automation adapter plug-in configurationfile” on page 25.

Observed stateThe end-to-end automation-specific resource status information that is

Appendix B. SA z/OS specific implementation of the end-to-end automation resource data model 67

||

||

|

|

||

||

|||

|||

|||

||||

|

|

||

||

|||||

||

|||

|||

||||||

||

derived from the automation manager status of SA z/OS. For mappingdetails see “Status mapping” on page 76.

Desired stateThe end-to-end automation-specific resource status information that isderived from the automation manager status of SA z/OS. For mappingdetails see “Status mapping” on page 76.

Request offline/onlineThe automation adapter converts these functions to SA z/OS specificcommands. For details concerning these requests see “Requests issued bythe operations console and the end-to-end automation manager” on page69.

Cancel requestThe automation adapter converts these functions to SA z/OS specificcommands. For details concerning these requests see “Requests issued bythe operations console and the end-to-end automation manager” on page69.

View requestsThis lists requests and votes in a similar way to INGVOTE.

Suspend/Resume automationThis allows you to enable and disable the automation flag of a resourcethat is maintained by the automation manager.

There are additional properties for a resource object:

There is resource status information about the automation manager for SA z/OS:v The SA z/OS compound statusv The SA z/OS observed statusv The SA z/OS desired statusv The SA z/OS health status

It shows the SA nature if the resource is a group and it shows the SMFID of thecorresponding system.

The Last Compound Status Change such as 2015-08-10 07:41:59 +0000 is theGMT date and time when the compound status of the resource has been changed.

Top level resourceTop level resources consist of:v All z/OS systems in the sysplex as defined in the automation policyv All members of type APL or APG that are attached to resources

system/SYG/system, but not included as members in any other group, wheresystem is any z/OS system of the sysplex as defined in the automation policy

v All Monitor resources (*/MTR/*)

Relations to resource objectsWhen requesting relations the following relationship types are listed:v MakeAvailablev MakeUnavailablev HasParentv HasPassiveParentv Externally


||

||||

|||||

|||||

||

|||

|

|

|

|

|

|

||

||

||

|

|||

|

||

|

|

|

|

|

v HasMonitorv ForceDownv PrepAvailablev PrepUnavailable

Request issued to resource objects

For a resource requests are shown.

Requested actionOnline for MakeAvailable requests, Offline for MakeUnAvailable requests.

SourceSource of the request, indicating who made the request, for example,OPERATOR or E2EMGR.

User IDID of the operator or automation manager that made the request.

PriorityValue Low, High or Force, depending on the priority assigned to therequest in SA z/OS:

Low Priority <2,000,000

High 2,000,000≤ Priority <3,000,000

Force 3,000,000≥ Priority <4,000,000

CreatedThe date and time when the request was issued.

Type Type of the request, indicating whether it is a request or a vote.

Requests issued by the operations console and the end-to-endautomation manager

The end-to-end automation GUI or manager can send requests to the automationadapter.

These incoming end-to-end automation requests are mapped to SA z/OScommands as listed in Table 8.

Table 8. Mapping of end-to-end automation requests to SA z/OS commands

End-to-endautomation requestname SA z/OS command1

Online INGREQ resource REQ=START SCOPE=ONLY SOURCE=sourceUSERID=requestor WAIT=time CMT=comment

Offline INGREQ resource REQ=STOP SCOPE=ALL SOURCE=sourceUSERID=requestor WAIT=time CMT=comment

CancelRequest INGSET KILL resource REQUEST=* SOURCE=source WAIT=time

IncludeNode INGSET CANCEL system/SYG/systemREQUEST=MAKEUNAVAILABLE SOURCE=source WAIT=time

ExcludeNode INGREQ system/SYG/system REQ=STOP SOURCE=sourceUSERID=requestor WAIT=time CMT=comment

ResetFromNRE SETSTATE resource AUTODOWN TARGET=system


|

|

|

|

|

|

||

|||

||

|||

||

||

||

||

||

Table 8. Mapping of end-to-end automation requests to SA z/OS commands (continued)

End-to-endautomation requestname SA z/OS command1

SuspendResource INGSET SET resource AUTOFLAG=NO WAIT=time

ResumeResource INGSET SET resource AUTOFLAG=YES WAIT=time

MoveAwayMoveHomeMoveTo

INGMOVE resource OUTMODE=LINE WAIT=timeTO=*ANY|*HOME|system

1. These commands also take the parameters OUTMODE=LINE and VERIFY=NO.

MoveAway/MoveHome/MoveToThese requests move a resource to:v Any other systemv The resources's home systemsv A specific target system

Online/Offline/CancelRequestThe SOURCE can be either OPERATOR or E2EMGR.

IncludeNode/ExcludeNodeTo exclude a node, a stop request is issued to the system groupsystem/SYG/system with the effect that all resources known to theautomation are stopped. This might also include the automation managerand the automation agent, if they are defined as usual to the automation.

A subsequent IncludeNode request is only possible if the automation isstill running after having excluded the node. This comprises NetView andall dependant resources, the automation adapter and the automationmanager.

ResetFromNREThe ResetFromNRE request is to be used for resources that are in anon-recoverable error status. These resources are applications and monitorresources in the SA z/OS observed state HardDown, as described in“Status mapping” on page 76. Issuing the ResetFromNRE request mightnot be successful if the problem with the resource that produces theHardDown status has not been resolved.

The ResetFromNRE request is rejected for resources with agent statusCTLDOWN.

SuspendResource/ResumeResourceThese requests enable or disable the automation flag for a resource that ismaintained by the automation manager.

WAIT ParameterThe number of seconds for the WAIT parameter is calculated as thedifference between the time when the SA z/OS command was issuedwithin the NetView environment and the expiration time given to theend-to-end automation request.

The expiration time of an end-to-end automation request is determined byboth:1. The time when the corresponding end-to-end automation request was

issued from the GUI or the end-to-end automation manager


2. The timeout in seconds defined in the end-to-end automation server'sWebSphere Admin Console for the environment variablecom.ibm.eez.aab.invocation-timeout-seconds

An end-to-end automation request might be queued in the automationadapter or the NetView operator task for a period of time. You shouldtherefore make the environment variable com.ibm.eez.aab.invocation-timeout-seconds that is defined in the WebSphere Admin Console largeenough to take this delay into account.

The calculated time difference is taken for the WAIT parameter. This valueis shortened to 999 seconds if it exceeds this maximum value given bySA z/OS. If at the other side the calculated value for the WAIT parameteris less than a given minimum value, the requested command will berejected.

This minimum value is given by an advanced automation option (AAO)for different requests, as follows:

Request AAO

Online, Offline and ExcludeNode INGREQ_WAIT

CancelRequest INGSET_WAIT

ResetFromNRE INGLIST_WAIT

If the appropriate common global variable is not set, 30 seconds isassumed as minimum value.

The calculated time difference is evaluated directly before the requestedcommand is to be issued.

If, for example, the original timeout for the end-to-end automation requestis 2500 seconds, and the remaining time directly before issuing theSA z/OS command from the primary agent is still 2000 seconds, it will beshortened to 999 as the maximum value. If the value of 999 seconds is tooshort for command execution, it can happen that the command times out,even though the end-to-end automation timeout value is very large.

For example, if the calculated time difference directly before issuing anOnline request is 35 seconds, and thus less than the minimum value of 40seconds that is provided in the common global variable INGREQ_WAIT,the requested command will be rejected, and an error message issued tosay that the task execution request timed out.

Overwriting commandsThe SA z/OS commands that result from Table 8 on page 69 can be overwritten inthe authorization user exit, as described in sample exit AOFEXE2E. But keep inmind that the overwritten command is no longer validated by SA z/OS. Thus youmust ensure that the overwritten command can be executed without errors.

Request priorityBy default, incoming requests from the end-to-end automation manager areexecuted with a low priority and they are sorted behind requests from OPERATORand AUTOOPS in the hierarchy of all possible requests.

However the default value of the priority parameter for INGREQ commands fromthe end-to-end automation manager can be changed via advanced automationoptions by changing the value of the global variable INGREQ_PRI.E2EMGR.


For further details about the hierarchy of requests, see the chapter "Concepts" inIBM Tivoli System Automation for z/OS User's Guide.

Disregarding the hold flagBecause requests from the end-to-end automation manager are handled like thosefrom SA z/OS operators, they cause the hold flag for a resource to be overruled.

This means that if a resource reference has a desired state of online, the end-to-endautomation manager issues a start request for it after the referenced SA z/OSresource is started (after an automation agent restart), even though the NOSTARToption is specified for the resource.

INGE2EPurpose

The INGE2E command provides the operational API for the end-to-end automationadapter.

►►NETVASIS

INGE2E function options ►◄

function options:

RESYNCRECYCLE,move-groupSETDBGLVL NORMAL

NORMAL,EXPNORMAL,EXP,SEC

DELDBGLVLDISPCFG CPATH=custom_pathVERIFY CPATH=custom_path JOBEAS=jobname

PING=NOPREPARE IPATH=install_path CPATH=custom_path SERVER=hostname

JAVA=32bit_java_path

Parameters

RESYNCSpecifies resynchronizing the end-to-end automation manager with thefirst-level automation. For this purpose the automation manager is firstnotified that the automation domain is offline and then it is set to onlineagain. This causes the end-to-end automation manager to request initialstatus information for all resources known by it in that automationdomain.

RECYCLESpecifies recycling a MOVE group. The MOVE group is part of theend-to-end automation high availability policy as described in Chapter 9,“Operating the end-to-end automation adapter via SA z/OS,” on page 41The MOVE group includes the end-to-end automation adapters on thedifferent systems within a subplex. The INGE2E command is specified inREFRESHSTART of the entry type E2E_ADPT in the STARTUP policy. Itrecycles the MOVE group either by recycling the primary automationagent, or by a refresh or an ACF COLD of the configuration file.

move-groupThe name of the MOVE group to be recycled.


||||||||||||||||||||

|

|

|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

|

|

Example to recycle the MOVE group E2E_ADPT_X/APG, specify:INGE2E RECYCLE, E2E_ADPT_X/APG

SETDELDBGVLUse this function only if IBM Support asks you to do so. Set ON debuglevel for the End-to-End Adapter REXX backend.

NORMALThe standard debug level.

EXPSpecifies to debug expiration checking.

SECSpecifies to debug security user exit.

DELDBGVLUse this function only if IBM support asks you to do so. Deletes all debuglevels for the End-to-End Adapter REXX backend.

VERIFYVerifies the installation of the end-to-end adapter. Requires that you havecopied and customized the end-to-end adapter configuration files.

Requires that the E/AS is already running.

Requires that the operator that calls function VERIFY has rights to accessOMVS and to access files and subdirectories within CPATH.

JOBEASSpecifies the jobname of the E/AS address space.

CPATHSpecifies the customization path of the end-to-end adapter. This is thedirectory that contains the subdirectory /config. For example,local/ing/adapter.

PING

Specify NO if you do not want to send a ping to the hostname.

If you omit this parameter or you set it to anything else than the NOfunction, VERIFY checks if the ping to the hostname works correctly.

This function verifies:v GRPID in INGXINIT must match GRPID in USS file

ing.adapter.plugin.properties.v ServerLocation in E/AS message adapter configuration file must match

eif-recieve-from-hostname in USS file ing.adapter.properties.v ServerPort in E/AS configuration file must match eif-receive-from-

hostname in USS file ing.adapter.properties.v PPI parameter in E/AS start procedure must match INGEVE2E or

Cglobal AOF_E2E_EAS_PPI.v PPI=YES must be set in INGXINIT.v E2E_CUSTOM_ROOT in USS file ingadapter.properties must match

value of CPATH.v E/AS is not running.v Performs PING to eif-send-to-hostname in USS file

ing.adapter.properties.


|

|

|||

||

||

||

|||

|||

|

||

|

|

||

|

||

||

||

||

|

||

|

||

If verification was not successful it writes information text to the consolethat describes the parameter mismatch in more detail.

Example:NETVASIS INGE2E VERIFY JOBEAS=EVE2E CPATH=/local/ing/adapter

DISPCFGReads end-to-end adapter configuration files from the custom-rootdirectory CPATH and displays them all one after another on the NetViewWINDOW.

Example:NETVASIS INGE2E DISPCFG CPATH=/local/ing/adapter

PREPAREThis function prepares the USS configuration files for the end-to-endadapter and completes the following:1. creates necessary subdirectories within the custom-root directory,2. copies all necessary configuration files from the install-root to the

custom-root,3. updates the configuration files with the input parameters.

Note: If the directory structure already exists then the command INGE2EPREPARE stops with an error message in order to prevent overwrite anexisting configuration.

IPATH Specifies the install path of the end-to-end adapter. The default install pathis /usr/lpp/ing/adapter.

CPATHSpecifies the customization path of the end-to-end adapter. The functionPREPARE or the end-to-end adapter writes into this directory.

All subdirectories are automatically created.

This is the subdirectory that for example contains the subdirectory /configor /data.

For example /local/ing/adapter.

SERVERSpecify the end-to-end management server hostname.

JAVA Optionally specify the 32-bit java home directory, for example,/local/java/a60/j6.0

You may omit this parameter if the default java runtime is already 32-bitjava version 1.6.

Example:NETVASIS INGE2E PREPARE IPATH=/user/lpp/ing/adapter

CPATH=/local/ing/adapterSERVER=lnxe2e4x JAVA=/local/java/a60/J6.0

Example

To recycle the MOVE group E2E_ADPT_X/APG, specify:INGE2E RECYCLE,E2E_ADPT_X/APG


||

|

|

|||

||

Example verification output

When you issue on the NetView console commandNETVASIS INGE2E VERIFY JOBEAS=neteve2z CPATH=/local/ing/adapter

the following output may be viewed:01 SA agent GRPID.........................................: 3402 SA agent PPI...........................................: YES03 E/AS message adapter jobname...........................: NETEVE2Z active04 E/AS message adapter PORT..............................: 552905 E/AS message adapter IP................................: 127.0.0.106 E/AS message adapter PPI...............................: INGEVE2E07 E2E adapter PPI........................................: INGEVE2E08 E2E adapter EIF PORT...................................: 552909 E2E adapter EIF IP.....................................: 127.0.0.110 E2E adapter GRPID......................................: 3411 E2E adapter automation domain..........................: KEYAPLEX INGXSG3412 E2E adapter automation operators.......................: all active13 E2E adapter adapter custom root directory..............: /local/ing/adapter14 E2E adapter install root directory.....................: /usr/lpp/ing.adapter15 E2E adapter java home directory........................: /local/java/a60/J6.016 E2E management server hostname.........................: lnxe2e4x17 E2E management server hostname ping....................: successful

18 Verification was successful

Explanation of the output01 Parameter GRPID extracted from currently used member INGXINIT.

See LISTA DSIPARM,INGXINIT02 PARAMETER PPI extracted from currently used member INGXINIT.

See LISTA DSIPARM,INGXINIT03 Jobname of the E/AS address space which must be active.04 Parameter ServerPort of the E/AS message adapter configuration file.

Will be extracted from running system via command F JOBEAS,settings, task=messagea05 Parameter ServerLocation of the E/AS message adapter configuration file.

Will be extracted from running system via command F jobeas,settings,task-messagea06 Parameters PPI from E/AS initialization configuration file.

Will be extracted from running system via command F jobeas,display, status07 PPI queue name used to send events to the End-to-end automation adapter via E/AS.

Default name is INGEV2E or extracted from the following AAO: AOF_E2E_EAS_PPI08 Parameter eif-receive-from-port extracted from USS file

ing.adapter.properties09 Parameter eif-receive-from-host-hostname extracted from USS file

ing.adapter.properties10 Parameter GRPID extracted from USS file11 Parameter plugin-domain-name extracted from USS file

ing.adapter.plugin.properties12 Automation operators E2EOPER and E2EOPRnn must be defined and all active.

At least 4 must be active or if more definedall must be active. See command DISPAOPS and seealso entry E2EAUTOOPS and see entry E2E_AUTOOPS in *E2E best practices policy.

13 Parameter E2E_CUSTOM_ROOT extracted from ingadapter.properties14 Parameter E2E_INSTALL_ROOT extracted from ingadapter.properties15 Parameter E2E_JAVA_HOME extracted from ingadapter.properties.

If not specified then the string "default" is shown16 Parameter eif-send-to-hostname extracted from USS file

ing.adapter.properties17 A NetView PING command is used to check if the TCP/IP connection

to the end-to-end management server host can be established.A firewall might cause an error. Note a firewall might cause an error.You may specify parameter PING=NO to avoid checking the ping.

18 If all checks were successful, you will get this messageing.adapter.plugin.properties


|

|

|

|

|||||||||||||||||||

|

||||||||||||||||||||||||||||||||||||

Status mappingThis section gives details of the mapping of statuses between the SA z/OSautomation adapter and end-to-end automation server.

IntroductionThe SA z/OS automation manager maintains the following status information foreach automated resource:

About this taskv Observed Statev Desired Statev Automation Statev Startable Statev Compound Statusv Health State

This must be mapped to the following end-to-end automation resource data modelstatus information:v Observed Statev Desired Statev Operational Statusv Compound Status

Note that not all values that are available are used. For a full list of status values,refer to System Automation for Multiplatforms End-to-End Automation Management.

The following rule is applied to this mapping:v The mapping between the values of the automation manager status fields and

the status fields of the end-to-end resource data model is only based on theactual status values of the resource. The status history of any of the values doesnot influence the resulting status values.

Status mapping stepsAbout this task

The mapping is carried out in three steps:

Procedure1. The SA z/OS statuses observed state, desired state and automation state are

mapped to the observed state, desired state and operational state of theend-to-end automation resource data model. See “Step 1” on page 77

Note: There is a direct one-to-one mapping of the SA z/OS desired state to theend-to-end automation desired state.

2. If, as a result of the first step, the operational status is OK, the second step isused to degrade the operational state, if the SA z/OS compound state reports aproblem. See “Step 2” on page 78.

3. The compound state of the end-to-end resource data model is derived from theoperational state. See “Step 3” on page 78.


Step 1About this task

The following sub-steps are made:

Procedure1. In this step, the health status is not directly mapped to the end-to-end

automation resource data model. It is, however, implicitly mapped through thecompound status (see “Step 2” on page 78).

2. The SA z/OS desired status values Available and Unavailable correspond tothe values Online and Offline of the end-to-end automation desired state. Othervalues of the end-to-end automation are ignored.

SA z/OS desired status End-to-end automation desired state

Available ⇒ Online

Unavailable ⇒ Offline

3. An automation status of Unknown is mapped to the operational statusUnknown, regardless of the other statuses.

SA z/OS automation state End-to-end automation operational status

Unknown ⇒ Unknown

4. Table 9 shows the SA z/OS automation manager status mapping. Note that theSA z/OS desired state is mapped directly to the end-to-end automation desiredstate (which is given in the table).

Table 9. SA z/OS automation manager status mapping.

SA z/OS automation manager status End-to-end automation resource data model status

Observed state Desired stateAutomationstate ⇒ Observed state Operational state

Available * Problem ⇒ Online Error

Available * * ⇒ Online Ok

WasAvail * * ⇒ Online LostCommunication

SoftDown * Problem ⇒ Offline Error

SoftDown * * ⇒ Offline Ok

HardDown * * ⇒ OfflineFor APLs: NonRecoverableErrorFor other resource types: Error

Standby * Problem ⇒ Offline Error

Standby * * ⇒ Offline Dormant

Starting * Problem ⇒ Starting Error

Starting * * ⇒ Starting InProgress

Degraded * * ⇒ Online Degraded

Stopping * Problem ⇒ Stopping Error

Stopping * * ⇒ Stopping InProgress

Problem Available * ⇒ Starting Error

Problem Unavailable * ⇒ Stopping Error

SysGone * * ⇒ Offline SupportingEntityInError


Table 9. SA z/OS automation manager status mapping (continued).

SA z/OS automation manager status End-to-end automation resource data model status

Observed state Desired stateAutomationstate ⇒ Observed state Operational state

Unknown * * ⇒ Unknown NoContact

* indicates that this can be any valid value.

Step 2The second step is used to degrade the operational state if the SA z/OS compoundstate reports a problem. The degradation is done in combination with the desiredand observed status according to Table 10.

Table 10. Status mapping: second step if the SA z/OS compound status reports a problem

SA z/OS compound status Desired status Observed status Operational state

Degraded * * ⇒ Degraded

Awaiting Online Offline ⇒ StartReqPending

Awaiting Offline Online ⇒ StopReqPending

Denied Online Offline ⇒ StartInhibited

Denied Offline Online ⇒ StopInhibited

Inhibited Online Offline | Stopping ⇒ StartInhibited

Inhibited Offline Online | Starting ⇒ StopInhibited

Inhibited Online Online ⇒ StopInhibited

Inhibited Offline Offline ⇒ StartInhibited

Problem * * ⇒ Error

* indicates that this can be any valid value.

For example, the operational state will be degraded in this second step, if thehealth status is degraded, which impacts the compound status of SA z/OS.Another reason for a degraded compound status of SA z/OS might be anautomation flag that is switched off.

Step 3The compound status of the end-to-end resource data model is derived from theoperational state according to the following table:

Operational state Compound status

Unknown ⇒ Warning

Ok ⇒ Ok

Degraded ⇒ Warning

Error ⇒ Error

NonRecoverableError ⇒ Fatal

NoContact ⇒ Warning

LostCommunication ⇒ Warning

Dormant ⇒ Ok

SupportingEntityInError ⇒ Error

StartInhibited ⇒ Warning


Operational state Compound status

StopInhibited ⇒ Warning

StartReqPending ⇒ Warning

StopReqPending ⇒ Warning

InProgress ⇒ Warning



Appendix C. Messages

This information lists the messages that are issued either by the automationadapter or the automation adapter plug-in.

Note that within NetView an additional * may be appended to the end of themessage text for EEZNnnnn, INGX97nn, INGX98nn, and INGX99nn messages.

End-to-end automation adapter messagesThe following messages are issued by the automation adapter.

EEZA0001E Syntax error on line line number

Explanation: A syntax error has occurred in theconfiguration file, for example, a leading = on a line.

System action: The automation adapter stops.

Operator response: Analyze the configuration file forinvalid syntax.

EEZA0002E Wrong datatype in key the key. Expectedthe desired type, found value "the valuethat was found"

Explanation: The value of the given key cannot beinterpreted as the desired type. For example, thesystem expected a boolean value but found the string“hello”.


Operator response: Analyze the configuration file forinvalid key/value pairs.

EEZA0003E The key "the key that was not found" wasnot found and no default value wasgiven

Explanation: The system wanted to retrieve from theconfiguration file a value that did not exist and nodefault value was given.


Operator response: Supply a value for the key in theconfiguration file.

EEZA0004E Integer out of bounds in key "the key".Expected value between the lower boundexpected and the upper bound expected,found the value parsed

Explanation: The system expected an integer valuebetween the given bounds (inclusive) for the given key,but found a value outside these bounds.


Operator response: Supply a value within the givenbounds for the key.

EEZA0006E Cannot create an instance of the classbecause class not found: class name

Explanation: The automation adapter cannot load theclass.

System action: The automation adapter rejects therequest.

Operator response: Check whether the class name isvalid and is available in the corresponding classpath.

EEZA0007E Cannot create an instance of the classbecause method not found: class name

Explanation: The automation adapter can load theclass but cannot create an instance.


Operator response: Check whether the class is valid.

EEZA0008E Cannot create an instance of the classbecause of an unknown error: class name

Explanation: The automation adapter cannot load theclass or create an instance.


Operator response: Check whether the class is validand analyze the attached original exception.

EEZA0009E Invocation of adapter plug-in failed:plug-in=plug-in name, method=methodname, internalRetcode=internal returncode, taskRetcode=task return code

Explanation: The automation adapter client API wascalled to execute a task on the remote automationadapter. There are three error categories:


v The client suffers an error on the connection

v The execution of the task within the automationadapter backend failed

v Execution failed in the automation adapter plug-in.

Automation adapter internal return codes:3 Backend detects that the request expired before it

was started.4 Backend cannot be loaded.22 Backend cannot load the plug-in Java class.23 An exception occurred in the backend or the

plug-in returns a non-zero task return code.24 Backend rejects the execution of the task. See the

automation adapter trace for details.30 Backend detects invalid input arguments. Cannot

execute task. This is an internal error.40 Authentication failed. The user ID or password has

not been specified or an internal error occurred.41 Authentication failed. The user ID or password is

invalid on the automation adapter host.42 Authentication failed. The user ID has been

revoked. JAAS login modules may not provide thisinformation or may also use it if the password hasexpired.

43 Authentication failed. The password has expired.JAAS login modules may not provide thisinformation.

The automation adapter client connection internalreturn codes:

101Connection timed out while open.

102Connection failed during open/read/write becausepeer closed.

103Not all data received. The data was readsuccessfully but the number of bytes is too small.This might be an internal error.

104Unable to connect to the automation adapter.

105Unable to close connection. This might be aninternal error.

106Unable to send data. Connection has been aborteddue to, for example, SSL mismatch or theautomation adapter stopped.

107Marshal error occurred while sending or receivingdata. This is an internal error.

108Connection is invalid, for example, connection hasnot been opened or previously failed.

109Read response failed. Data is zero, for example, theconnection has been aborted due to an SSLmismatch.

110Connection timed out during read/write.

Predefined task return codes from plug-in:<0 Internally used task return codes have been

mapped to one of the automation adapter returncodes.

0 The plug-in was successful.4004

The plug-in connection timed out.4008

The plug-in authorization is missing to execute therequest.

4009The plug-in authentication failed.

4012The plug-in failed but might execute the nextrequest successfully. This is the default return codeif the plug-in throws an exception but the plug-inreturn code is zero.

4016The plug-in failed and might not execute the nextrequest successfully.

4020The plug-in failed and forces the entire automationadapter to stop.

System action: Execution of the remote task fails.

Operator response: Analyze the return codedescription. If it is an internal error, check IBMElectronic Support for additional information -http://www.ibm.com/support/entry/portal/

EEZA0010E Request expires before the adapterpasses it to the adapter plug-in. Timeoutperiod is timeout value seconds

Explanation: All requests have an associatedexpiration date. The request is scheduled to anexecution thread that detected that the expiration timehad expired.


Operator response: Analyze the reason (for example,high working load). Increase the timeout period ifnecessary.

EEZA0011E The backend program specification isinvalid

Explanation: The backend program is not a Javaprogram or the Java program name was not specified.


Operator response: Check the program that called theautomation adapter client API.

EEZA0010E • EEZA0011E


EEZA0012E Invalid parameter list

Explanation: The automation adapter detected arequest that is associated with an invalid parameter list.


Operator response: Check the program that called theautomation adapter client API.

EEZA0013E Authentication for user ID user namewas unsuccessful

Explanation: The request is associated with a user IDand password that have been validated unsuccessfully.


Operator response: Check whether the user ID isauthorized for the system and check the security policy.Also check if you have stored a user ID and passwordfor this domain in the credential store of the DashboardApplication Services hub.

EEZA0014E The original exception original-classneeds to be transported to the remotecaller

Explanation: An exception from an underlyingcomponent needs to be transported to the remote caller.

System action: None.

Operator response: Analyze the original exceptionattached with this message.

EEZA0015E Method not supported: name of themissing method

Explanation: The automation adapter detected anunknown method name. The list of all valid methodnames is defined in the EEZAdapterInteractioninterface.


Operator response: Check IBM Electronic Support foradditional information - http://www.ibm.com/support/entry/portal/

EEZA0017E Request not supported: name of theunsupported request

Explanation: The automation adapter plug-in does notsupport the specified request.

System action: The request might be rejecteddepending on the behavior of the plug-in.

Operator response: Check if the automation domainsupports this type of request.

EEZA0022E Adapter client is unable to connect tothe adapter at host:port due to exception:the exception that was caught

Explanation: The automation adapter client cannotconnect to the server at the given host and port. Theoriginal exception text is provided.

System action: The connection is not established.

Operator response: Analyze the original exception.

EEZA0023E Cache directory is invalid

Explanation: The EIF cache directory is not adirectory.


Operator response: Correct the configuration file.

EEZA0024E EIF sender and receiver must not beequal

Explanation: The EIF configuration parameters are notallowed to point to each other.



EEZA0025E Cannot find the plug-in configurationfile: configuration file name

Explanation: The master configuration file containsthe name of a plug-in configuration file that cannot befound.



EEZA0026E No plug-in configuration file wasspecified

Explanation: The master configuration file mustcontain at least one plug-in configuration file.



EEZA0027E Cannot load configuration file:configuration file name

Explanation: The specified configuration file cannot beloaded.




Appendix C. Messages 83

EEZA0028E Plug-in configuration file does notcontain all mandatory parameters:configuration file name

Explanation: The specified configuration file does notcontain all mandatory parameters. The plug-in is notused.

System action: The automation adapter does notdeploy the plug-in.


EEZA0029E Cannot create the first instance of theplug-in class: class name

Explanation: An attempt was made to create the firstinstance of the plug-in during initialization. Creationfailed.



EEZA0030E Cannot set up event subscription list forplug-in configuration file: plug-inconfiguration file name

Explanation: The specification of the EIF event classesin the plug-in configuration file is invalid.



EEZA0031E Cannot load configuration file from:plug-in configuration file name

Explanation: The automation adapter cannot load thespecified configuration file because either noconfiguration file or an invalid one was specified.


Operator response: Check whether the name of theconfiguration file is correct.

EEZA0032E Initialization of the adapter failed:original exception

Explanation: An error occurred in the initializationstep of the automation adapter.


Operator response: Analyze the associated exception.If there is no exception text for this message, try to findadditional messages that were sent previously.

EEZA0033E Unable to create type of factorySocketFactory

Explanation: The automation adapter server or clientcannot create a socket factory for the remote contact.

System action: The automation adapter client cannotcreate a connection or the automation adapter servercannot receive connections.

Operator response: Analyze the reason using previousmessages.

EEZA0036E The adapter suffered an unexpectedinterruption: original exception

Explanation: The automation adapter waits for atermination command. An unexpected interruptionoccurred.


Operator response: Analyze the original exception.

EEZA0037E The adapter stops because no plug-inhas been successfully initialized

Explanation: At least one plug-in must have beensuccessfully initialized otherwise the automationadapter stops.


Operator response: Analyze previous messages andexceptions issued by the failing plug-in.

EEZA0038E A (SSL) socket configuration erroroccurred: exception text

Explanation: An error occurred during the loading orprocessing of (SSL) socket-related configuration data.An SSL handshake exception will only be reportedduring initial contact.

System action: The automation adapter client cannotcreate a connection or the automation adapter servercannot receive connections.

Operator response: Analyze the exceptions text.Check the SSL configuration file,ing.adapter.ssl.properties, if necessary.

EEZA0039E Not all data was read from socket:number of bytes read bytes read, number ofbytes expected bytes expected to be read

Explanation: The incoming request has a length inbytes, but not all bytes can be read.


Operator response: Check why the socket connectionwas broken while transferring data.



EEZA0040E The adapter client cannot establishconnection to the adapter: stringrepresentation of the connection

Explanation: Opening the connection failed. A requestcannot be sent to the automation adapter. The stringrepresentation of the connection contains details aboutthe connection.

System action: The automation adapter frontendfailed.

Operator response: Analyze the connectioninformation.

EEZA0041E The adapter client cannot invoke anadapter request: InternalRC=internalreturn code, TaskRC=task return code

Explanation: A connection to the automation adapterhas been successfully established. The automationadapter frontend might have sent a request to theautomation adapter but the request failed. If theinternal or task return codes are not applicable (n/a),some other unexpected exception occurred.


Operator response: Analyze the internal and taskreturn codes (see EEZA0009E for an explanation of thereturn codes).

EEZA0042E The adapter has thrown a remoteexception: InternalRC=internal returncode, TaskRC=task return code. Theoriginal message was: message text

Explanation: A connection to the automation adapterhas been successfully established. The automationadapter frontend has sent a request to the automationadapter but the plug-in has thrown an exception.


Operator response: Analyze the internal and taskreturn codes (see EEZA0009E for an explanation of thereturn codes).

EEZA0043E A required command line parameter ismissing

Explanation: One of the required command lineparameters is missing (such as -start,-stop or-terminate).


Operator response: Specify the requiredcommand-line parameters and try again.

EEZA0045E The adapter cannot establish a serversocket due to illegal arguments: exceptiontext

Explanation: The automation adapter cannot establisha receiver thread and cannot accept incomingconnections.


Operator response: Analyze the configuration file foran invalid IP address.

EEZA0047E The adapter is unable to acceptconnections due to socket exception"exception"

Explanation: An exception occurred as the automationadapter was about to accept an incoming connection.


Operator response: Analyze the exception text.

EEZA0051W Termination of the adapter failed due toexception: error message

Explanation: The attempt to stop the receiver threadfailed because an exception occurred.


Operator response: Analyze the exception text.

EEZA0052E Cannot create an in-storage EIFconfiguration file: exception text

Explanation: An instance of the Java classByteArrayInputStream cannot be created or written.


Operator response: This is probably an internal error.The exception text might give the reason for theproblem.

EEZA0053E Missing argument for command lineparameter "the parameter"

Explanation: A required argument for a command lineparameter (such as -start) is missing. For example,AdapterCmd -start would be incorrect because -startrequires an argument. A correct example would be:AdapterCmd -startcom.ibm.ing.saplugin.INGXPluginInvocation

System action: Processing of this command ends.

Operator response: Check the documentation forinformation about valid command line arguments andtheir parameters.



EEZA0055E Remote Contact inactivity thresholdexceeded: elapsed seconds=elapsedseconds threshold=threshold

Explanation: The automation adapter calculates theelapsed time since the last synchronous request wasreceived. The automation adapter stops itself if thistime exceeds the number specified in the parametereez-remote-contact-activity-interval-seconds. Anyincoming event is used as a trigger for the calculation.


Operator response: You might want to increase thenumber of seconds specified by the parametereez-remote-contact-activity-interval-seconds. Setting thisparameter to 0 (zero) means it never expires.

EEZA0056I Initial contact was enabled and theconnection to the management serverhas been established

Explanation: The parameter eez-initial-contact was setto true and the automation adapter attempted toconnect the management server. The handshake to themanagement server was successful.


Operator response: No action required.

EEZA0057E The connection to the managementserver cannot be established

Explanation: The automation adapter stops attemptingto connect to the management server because thetimeout interval is over.


Operator response: You might want to increase thenumber of minutes specified by the parametereez-initial-contact-retry-interval-minutes. Specify thevalue 0 (zero) in order to retry forever.

EEZA0058E The plug-in has not been deployed ornot yet started: name of the Java plug-inclass

Explanation: An attempt was made to issue a requestagainst a non-deployed plug-in or a plug-in that hasnot been started.


Operator response: Check the plug-in configurationfile and deploy the missing plug-in class. Search formessage EEZA0115I.

EEZA0059E An internal error occurred

Explanation: The automation adapter detected aninternal error.


Operator response: Check IBM Electronic Support foradditional information - http://www.ibm.com/support/entry/portal/

EEZA0060I The termination of the adapter isdelayed for duration of the delay in secondsseconds

Explanation: Stopping the automation adapter isdelayed for a short while until it has sent theappropriate domain leave events. You can configure theduration of this delay with the eez-stop-delay-secondsparameter.

System action: The automation adapter attempts tosend domain leave events.


EEZA0061E Unable to bind a socket to addresseez-remote-contact-hostname at porteez-remote-contact-port. Reason: message ofthe exception

Explanation: The automation adapter was unable touse this address or port. Possible causes of the problemare:

v The port is already in use by another program.

v The address could not be assigned.


Operator response: Make sure that no program isusing this port (that is, an automation adapter that isalready running). If another program needs this port,then configure the automation adapter to use anotherport (with the eez-remote-contact-port parameter in themaster configuration file). Ensure that the address isvalid.

EEZA0062I The start command of the automationplug-in name of the Java plug-in class wassuccessful

Explanation: The selected automation plug-in wassuccessfully started.

System action: The automation adapter has started theautomation plug-in.


EEZA0055E • EEZA0062I


EEZA0063I The stop command of the automationplug-in name of the Java plug-in class wassuccessful

Explanation: The selected automation plug-in wassuccessfully stopped.

System action: The automation adapter has stoppedthe automation plug-in.


EEZA0064I The termination command for theadapter was successful

Explanation: The automation adapter was successfullystopped.



EEZA0070E The host name eez-remote-contact-hostnameis unknown

Explanation: The automation adapter was unable toresolve the host name.


Operator response: Specify a valid host name.

EEZA0071E The domain name is either null orempty

Explanation: The plug-in returned an invalid domainname since it is either null or empty.

System action: The plug-in cannot be started.

Operator response: Specify a valid domain name inthe plug-in configuration file.

EEZA0100I The adapter has been started

Explanation: This is the first of a sequence of threemessages until the automation adapter is ready. Theautomation adapter starts initialization and will try toconnect to the management server ifeez-initial-contact=true.



EEZA0101I The adapter is active

Explanation: The automation adapter becomes“active” after a connection has been successfullyestablished to the management server. The automationadapter continues initialization, finds and starts up allplug-ins.



EEZA0102I The adapter is ready

Explanation: The automation adapter startup sequenceis complete.



EEZA0103I The adapter is stopping

Explanation: An internal or an external stop commandhas been received.

System action: The automation adapter is about tostop.


EEZA0104I The adapter has been stopped

Explanation: The automation adapter termination iscomplete. All possible stop delay periods are over. Theprocess stops immediately.

System action: The automation adapter has stopped.


EEZA0105I The adapter has been stopped due to afailure, rc=return code

Explanation: The automation adapter stopped becausean error occurred. All possible stop delay periods areover. The process stops immediately. The return codemight be:

12 if initial contact failed

13 if the remote contact activity threshold is exceeded

16 if a plug-in forced termination of the automationadapter

20 if initialization failed

24 if an error occurred after initialization wassuccessful

28 if an unsupported environment is detected


Operator response: Search for error messages thatwere issued previously. On z/OS return code 28 mightbe caused by the 64-bit JVM. You should use the 32-bitJVM instead.

EEZA0111I The plug-in is starting: name of the Javaplug-in class

Explanation: The automation adapter has alreadysuccessfully created an instance of the plug-in class andwill now call function INIT_DOMAIN.



EEZA0063I • EEZA0111I


EEZA0112I The plug-in has been started: name of theJava plug-in class

Explanation: The automation adapter plug-in hassuccessfully initialized the domain (INIT_DOMAIN).



EEZA0113I The plug-in is stopping: name of the Javaplug-in class

Explanation: The automation adapter will call plug-infunction TERM_DOMAIN.



EEZA0114I The plug-in has been stopped: name ofthe Java plug-in class

Explanation: The automation adapter plug-in hassuccessfully stopped the domain (TERM_DOMAIN).



EEZA0115I The plug-in startup failed: name of theJava plug-in class

Explanation: This message might follow afterEEZA0111I, but the attempt to start the plug-in viafunction INIT_DOMAIN failed. The automationadapter plug-in will not be started automatically.

System action: The plug-in will be disabled. A joinevent was not sent.

Operator response: You might want to restart theplug-in using the automation adapter start command.Analyze further plug-in messages.

EEZA0116I The status of the event sender changed:Address=address, Port=port, Status=status

Explanation: This message occurs if the status of theEIF connection changed. The reason could be that anew EIF connection is created or an existing EIFconnection is lost. The reason can be found in thestatus. A status= 'connection timed out' is expected ifthe SA Application Manager is stopped, for example,when the SA Application Manager moves to anothersystem and therefore the adapter needs to change theEIF sender destination. The status can be:

1 connection created

2 connection changed

4 connection closed

8 connection timed out



EEZA9991E The message file is not installed

Explanation: The English message file must beavailable.


Operator response: Make sure that the message file isin the class path

EEZA9992E EEZAdapterLogger is not available

Explanation: The automation adapter loggingcomponent has not been initialized.

System action: The automation adapter stops. Otherprocesses using the automation adapter client API willbe unable to write messages to log and trace files.

Operator response: Check IBM Electronic Support foradditional support - http://www.ibm.com/support/entry/portal/

EEZC0001I Setting up Tivoli Common Directory atlocation where Tivoli Common Directory isbeing set up.

Explanation: The Tivoli Common Directory path wasset to its default value, as shown in the message text.

System action: No system action required.

Operator response: No operator action required.

EEZC0002I Unable to determine Tivoli CommonDirectory. Diverting serviceabilityrelated output to alternative location.

Explanation: The system was not able to determinethe Tivoli Common Directory.

System action: Processing continues. The applicationwill attempt to divert serviceability related output toanother location for this session.

Operator response: In order to manage itsserviceability related output, the application should begranted read/write permission to the location/etc/ibm/tivoli/common (UNIX) or<Program_Files_Dir>\ibm\tivoli\common (Windows).

EEZC0003I Base output directory for serviceabilityrelated files (for example, message logfiles and trace files) has been set to newoutput directory.

Explanation: The output directory for serviceabilityrelated files was set to its default value, as shown inthe message text.

System action: From now on the application willwrite serviceability related information to the directorythat is contained in the message text.

EEZA0112I • EEZC0003I


Operator response: No action is required if the baseoutput directory for serviceability related files isacceptable. Otherwise, if it is required to relocate thebase output directory, modify the entry inlog.properties which should be located at<Program_Files_dir>\ibm\tivoli\common\cfg(Windows) or /etc/ibm/tivoli/common/cfg/log.properties (UNIX). Changes to this file will takeeffect once the corresponding component is restarted.

EEZC0004I Changing base output directory forserviceability related files of name oflogger from old output directory to newoutput directory.

Explanation: Due to changes in configuration settingsthe output directory of serviceability related files hasbeen relocated.

System action: From now on the system will writeserviceability related information to the new location.

Operator response: No action is required if the baseoutput directory for serviceability related files isacceptable. Otherwise, if it is required to relocate thebase output directory, modify the entry inlog.properties which should be located at<Program_Files_dir>\ibm\tivoli\common\cfg(Windows) or /etc/ibm/tivoli/common/cfg/log.properties (UNIX). Changes to this file will takeeffect once the corresponding component is restarted.

EEZK0003E String someString is too long: themaximum length of nameOfTheStringStrings is maxLength.

Explanation: Setting the String to the specified valuedid not succeed due to string length.

System action: The current task ends.

Operator response: Verify the input parameters. If theproblem persists, provide the trace file and thismessage text to IBM support.

EEZK0004E String named someStringName must notbe null and must not exceed themaximum length of maxLength.

Explanation: Setting the String to null is not allowed.

System action: The current task ends.

Operator response: Verify the input parameters. If theproblem persists, provide the trace file and thismessage text to IBM support.

EEZK0005E An exception, which is not an instanceof EEZApplicationException has beenpassed to theEEZApplicationTransientException. Thetype of the message is exceptionType. Theexception message is: exceptionMessage.

Explanation: This is an unexpected behavior.

System action: The current task will continue. Theexception will be processed.

Operator response: Provide the logs and traces formore details, please, if any error other error occurs.

End-to-end automation adapter plug-in messagesThe following messages are issued by the automation adapter plug-in.

ING230E Addressed consumer consumer notregistered. Event not forwarded.

Explanation: An event was received with a consumerwho was not registered as the target address. The eventcannot therefore be forwarded to the addressedconsumer.

The variable consumer shows the name of the eventconsumer who was specified as the target addressof the event that the event should have beenforwarded to.

System action: Processing of the event is terminated.

Operator response: None.

System programmer response: Check whether eventnotification has been correctly initialized andend-to-end automation has been registered as an eventconsumer.

ING231E event notification service returns rc.

Event not forwarded to receiver_id.

Explanation: The event could not be forwarded to theaddressed consumer via the PIPE stage TECROUTE.

The variable rc shows the return code to PIPE stageTECROUTE.

The variable receiver_id shows the name of the PPIreceiver ID.

System action: Processing of the event is stopped.


System programmer response: Check whether thestatus of the PPI receiver ID is active. The status of PPIreceivers can be listed with the command DISPPI.

ING232I PPI receiver ID for E2E adapter is set toreceiver_id.

Explanation: The PPI receiver ID for the messageadapter of the event/automation service, which is usedto forward events to the automation adapter, has been

EEZC0004I • ING232I


set to the specified receiver ID.



System programmer response: None.

ING233E Event forwarding task EVTOPER forE2E not defined.

Explanation: The primary agent cannot be startedbecause the automated function EVTOPER, which isused to forward the events to the automation adapter,has not been defined in the automation policy.

System action: Processing stops.


System programmer response: Define the automatedfunction EVTOPER.

ING234E Request 'request' failed: RC=rccommand='command' reason='reason'

Explanation: The specified command abended.

The variable request shows the request that wasreceived from the automation adapter for execution.

The variable rc shows the return code of thecommand.

The variable command shows the command thatimplements the request.

The variable reason shows text that describes theerror.

System action: Execution of the request stops.


System programmer response: Analyze the returncode and reason code for the abending command.

ING235W No information from automationmanager. event event not created forconsumer.

Explanation: An error occurred when requestinginformation from the automation manager that neededto be included in a domain event. The event has notbeen created.

v The variable event specifies the event to be created.Possible values are: READY, REFRESH, CHANGE.

A READY event is created at initialization time of theautomation domain and after having recovered frommiscellaneous error situations.

A REFRESH event is created after having refreshedthe configuration policy.

A CHANGE event is created after a takeover of theautomation manager if the outage has not exceeded agiven time interval.

v The variable consumer shows the name of the eventconsumer that the event should have been forwardedto.

System action: Processing of the event is stopped.


System programmer response: Analyze the NetViewlog for further SA z/OS messages concerning thecommunication between the primary agent and theautomation manager.

ING236W Task execution request request processedwith warnings: COMMAND='command'REASON='reason'

Explanation: A warning was issued when executing atask execution request. The message variables are:

request The name of the task execution request

commandThe command that failed.

reason Text that describes the error.

System action: The request is executed with warnings.


System programmer response: Analyze the reasoncode of the warning message.

ING237W Request 'request' processed withwarnings: COMMAND='command'REASON='reason'

Explanation: A warning was issued when executingan end-to-end request.

The variable request shows the name of theend-to-end request.

The variable command shows the issued commandthat implements the request.

The variable reason specifies the warning message.

System action: The end-to-end request executes.

Operator response: Analyze the reason code of thewarning message.


ING238E Task execution request tex_request failed:ERROR=error_code SERVICE='service'RC=return_code REASON='reason'

Explanation: The REXX function INGRXTX0 andcommon REXX macros issue this message if there is anerror. The message variables are:

tex_requestThe name of the task execution request

ING233E • ING238E


error_codeThe REXX function INGRXTX0 and thecommon REXX macros issue the followingerror codes:

1 RPC service failed: either INGPXSND,INGPXRCV or INGPXDEL.

2 Read from or write to the task executiondata stream failed.

3 Unknown task execution operation name.

4 Execution of a task execution requeststarted but failed. The REXX macro thatimplemented the execution of the requestdid not issue an error message. This is thedefault return code and the standardING238E message is written withSERVICE=OperationName andRC=OperationReturnCode.

5 Authorization error: the user that madethe request is not authorized to make it.

6 At least one request in the list of requestsfailed.

7 The execution of a task execution requestfailed for any other reason.

8 The execution of a task execution requestfailed because service INGPYAMC failed.

9 Execution of a task execution request wasrejected because the expiration time hadelapsed. See also The system programmerresponse for message ING249E.

10 User command executed but failedbecause return code is greater than zero.

11 Cannot start the user command becauseuser command not found on targetsystem.

12 Cannot start the user because commanduser id not defined on target system.

13 Cannot start the user command.

24 Task execution request contains no metadata.

28 The task execution command handleraborts because there is not enough time tosend back the response data. No responseis returned.

32 The task execution command handleraborts because of a REXX signaling error.

36 The automation adapter is not supportedby this product.

service The service that failed.

return_codeThe return code of the service that failed.

reason Text that describes the error.

System action: Execution of the request failed for thereason given in the message.


System programmer response: Check the netlog andcorrect the error.

ING239W Value in advanced automation optionname not valid. Default value used.

Explanation: The value provided in the advancedautomation option is not accepted as a valid value.

The variable name shows the name of the advancedautomation option.

The variable value shows the value of the advancedautomation option.

System action: Processing continues with the defaultvalue for the specified advanced automation option.


System programmer response: Correct the valueprovided in the advanced automation option.

ING240E Unexpected task execution request nametex_request.

Explanation: The REXX macro implemented toexecute the task execution request was called with anunexpected task execution request name.

The variable tex_request shows the name of the taskexecution request.

System action: Processing of the task executionrequest fails.

Operator response: Contact IBM Support.


ING241E Unexpected task execution element typetype.

Explanation: The REXX macro implemented toexecute the task execution request was called with anunexpected task execution request type.

The variable type shows the type of task executionelement.




ING239W • ING241E


|||

||||

|||

||

ING242E Cannot read task execution elementfrom data stream.

Explanation: The REXX macro implemented toexecute the task execution request cannot read the taskexecution element from the data stream.




ING243E Cannot write task execution element todata stream.

Explanation: The REXX macro implemented toexecute the task execution request cannot write to thedata stream to return data to the calling routine.




ING244E Invalid filter element name filter.

Explanation: The REXX macro implemented toexecute the task execution request was passed aninvalid filter element name.

The variable filter shows the name of the filterelement.




ING245E Duplicate filter element name filter.

Explanation: The REXX macro implemented toexecute the task execution request was passed duplicatefilter element names.

The variable filter shows the name of the filterelement.




ING246E Invalid combination of filter elementnames filter1 and filter2.

Explanation: The REXX macro implemented toexecute the task execution request was passed aninvalid combination of filter element names.

The variables filter1 and filter2 show the names ofthe two filter elements.




ING247E Invalid filter element filter. Filter valueunknown: value

Explanation: The REXX macro implemented toexecute the task execution request was passed anunknown filter value.

The variable filter shows the name of the filter.

The variable value shows the value of the filter.




ING248E Invalid filter element filter. Filteroperator unknown: operator

Explanation: The REXX macro implemented toexecute the task execution request was passed a filterelement with an unknown operator comparing the filtername and filter value.

The variable filter shows the name of the filter.

The variable operator shows the filter operator.




ING249E Execution of a task execution requesttimed out. The expiration time 'time' wastoo short – missing_time.

Explanation: The expiration time that was providedfor the task execution request was too short.

The variable time shows the expiration time thatwas provided for the task execution request.

The variable missing_time specifies the missing timeinterval.


Operator response: Contact your system programmer.

System programmer response:

Check the defined timeout interval for task executionrequests. If necessary, increase it as described in“Requests issued by the operations console and theend-to-end automation manager” on page 69.

ING242E • ING249E


If the timeout occurs during the INIT_DOMAINrequest, increase the TIMEOUT value ining.adapter.plugin.properties.

ING250E Execution of a service timed out. Theexpiration time time was reduced tonumber seconds.

Explanation: A service routine timed out withoutexploiting the expiration time that was provided for theexecution of the task execution request. The executiontime was reduced to the maximum value for the WAITparameter of the executed service.

The variable time shows the expiration time thatwas provided for the task execution request.

The variable number shows the value for the WAITparameter of the executed service.




ING251E Invalid combination of filter elementsfilter1 and filter2. Values value1 and value2are mutually exclusive.

Explanation: The REXX macro implemented toexecute the task execution request was passed aninvalid combination of values for the filter elements.

The variables filter1 and filter2 show the names ofthe two filter elements.

The variables value1 and value2 show the values ofthe two filter elements.




ING252E Domain initialization failed.Automation environment not initialized.

Explanation: Initialization of the automation domainfailed because initialization of the system automationenvironment of the primary agent has not yet beencompleted.

System action: The start of the automation adapterfails.

Operator response: Restart the automation adapterafter the initialization of the automation environment ofthe primary agent has completed.


ING253E Domain initialization failed. Primaryagent already started on system system.

Explanation: Initialization of the automation domainfailed because the primary agent is already running onanother system within the subplex.

The variable system shows the system name.


Operator response: Check whether the automationadapter should be stopped on the other system.


ING254E Domain initialization failed. PPIreceiver receiver of EAS not ACTIVE.

Explanation: Initialization of the automation domainfailed because the PPI receiver ID of the NetViewevent/automation service is not active.

The variable receiver shows the name of the PPIreceiver.


Operator response: Analyze the status of the PPIreceivers by using command DISPPI. Check whetherthe event/automation service has been started and hassuccessfully initialized its receiver ID at the PPI.


ING255E Requesting information fromAutomation Manager of domain domainfailed.

Explanation: Requesting information from automationmanager of an automation domain failed. Requestinginformation from automation is necessary during theinitialization of the automation domain or whenrequesting information about the automation domain.

The variable domain shows the name of theautomation domain.

System action: The task execution request fails.


System programmer response: Analyze the problem.Examine the NetView log for further information. If theproblem persists contact IBM Support.

ING256E Health check failed. Event forwardingswitched off.

Explanation: Events were lost when trying to forwardthem from the primary agent to the automationadapter. Event forwarding has therefore been switchedoff, which results in failing the health check of theautomation domain.

System action: The automation adapter will stop. A

ING250E • ING256E


subsequent restart enforces the re-initialization of theautomation adapter and a refresh of the statusinformation about first-level automation resources onthe end-to-end server.

Operator response: Check the communication pathfrom the primary automation agent to the NetViewevent/automation service. As soon as thecommunication path is available again, the automationadapter can be restarted.


ING257E Health check failed. PPI receiver receiverof EAS not ACTIVE.

Explanation: The PPI receiver identifier of theevent/automation service is not in the status ACTIVE.This results in failing the health check of theautomation domain.

The variable receiver shows the PPI receiver ID ofthe NetView event/automation service.

System action: The automation adapter does not senda heartbeat event, and so the communication status ofthe domain on the end-to-end automation serverchanges..

Operator response: Analyze the status of the PPIreceivers by using command DISPPI. Check whetherthe event/automation service has been started and hassuccessfully initialized its receiver ID at the PPI.


ING258E Execution of service service failed.Unexpected data received.

Explanation: The requested service did not return theexpected data.

The variable service shows the name of therequested service.


Operator response: Notify your system programmer.

System programmer response: Determine why theservice routine fails. Examine the NetView log foradditional information.

ING259E Invalid request element. Request nameunknown: name

Explanation: An end-to-end request with an unknownname was received.

The variable name shows the request name.




ING260E Invalid request element. Request typeunknown: type

Explanation: An end-to-end request with an unknowntype was received.

The variable type shows the request type.




ING261E Invalid request element. Multiplesolicited requests are not supported.

Explanation: Multiple solicited end-to-end requestswere received to be executed by the primary agent.Only one solicited end-to-end request can be accepted.




ING262W An attempt was made to overwrite atleast one restricted parameter. Inputparameters have been ignored:parameters

Explanation: An end-to-end request was received withparameters that attempted to overwrite restrictedparameters. The parameters are ignored.

The variable parameters shows a list of the ignoredparameters.




ING263E Request rejected because mandatoryparameter SOURCE is missing.

Explanation: An end-to-end request was receivedwithout the specified originator of the request viaparameter SOURCE.




ING264E Reset_from_NRE rejected because agentstatus of resource resource is CTLDOWN.

Explanation: A reset-from-non-recoverable-errorrequest was received for a resource that is in agentstatus CTLDOWN. Such a request is not supported for

ING257E • ING264E


resources in agent status CTLDOWN.

The variable resource shows the name of theresource that the request was issued for.


Operator response: Check the agent status of theresource that the request was issued for.


ING265E Reset_from_NRE rejected becauseobserved status of resource resource isnot HARDDOWN.

Explanation: A reset-from-non-recoverable-errorrequest was received for a resource that is not in statusHARDDOWN. Such a request is only supported forresources in status HARDDOWN.



Operator response: Check the status of the resource.


ING266E Reset_from_NRE failed because no datato resource resource received fromAutomation Manager.

Explanation: A reset-from-non-recoverable-errorrequest was received for a resource. An error occurredwhen requesting information from the automationmanager about the resource that the request was issuedagainst.



Operator response: Check whether the resource thatthe request was issued for is known to the automationmanager.


ING267E Reset_from_NRE rejected becauseresource resource is not of class APL.

Explanation: A reset-from-non-recoverable-errorrequest was received for a resource that is not of classAPL. This request is only supported for resources oftype APL.



Operator response: Check the type of the resource

that the request was issued for.


ING268E request rejected because system name ismissing.

Explanation: An end-to-end request concerning asystem was issued, but the system name was notspecified.

The variable request shows the name of theend-to-end request.


Operator response: Check that the request was issuedagainst a resource of class SYS.


ING269E Native command contains an invalidvalue for parameter $WAIT: wait

Explanation: An invalid value was specified as theWAIT parameter when issuing a native command.

The variable wait shows the value for the WAITparameter that was received.

System action: Processing of the task executionrequest fails



ING270E User user is not authorized to executecommand: command

Explanation: The execution of the specified commandis rejected by the authorization user exit AOFEXE2E.

The variable user shows the user ID that isassociated with the command.

The variable command shows the rejected commandresulting from the related end-to-end request.


Operator response: Contact your system programmerto obtain the necessary authorization to execute thecommand.

System programmer response: If it is appropriate,authorize the user to issue the specified command.

ING271E Command execution failed. Waiting forasynchronous output timed out.

Explanation: A timeout occurred when waiting forasynchronous output generated by a command thatwas issued from within a PIPE.


ING265E • ING271E


Operator response: Retry the operation. If theproblem persists, contact your system programmer.

System programmer response: Determine why thecommand does not return its output within theexpected time. Examine the NetView log for additionalinformation.

ING272E More than one request in a list failed.

Explanation: More than one request in a list ofrequests that were included in a task execution requestfailed.

System action: Processing of the related requests fails.

Operator response: Examine the NetView log foradditional information about the single requests thatwere processed with errors.


ING273W More than one request in a listprocessed with warnings.

Explanation: More than one request in a list ofrequests that were included in a task execution requestwere processed with warnings.

System action: Processing of the task executionrequest continues.

Operator response: Examine the NetView log foradditional information about the single requests thatwere processed with warnings.


ING274E A query to the automation managerfailed due to unsuccessful execution ofservice INGPYAMC.

Explanation: An error occurred when requestinginformation from the automation manager via theautomation manager API INGPYAMC.


Operator response: Check the communication pathfrom the primary agent to the automation manager andexamine the NetView log for additional information. Ifthe problem persists contact IBM Support.


ING275E Processing failed for command: command

Explanation: A command was called that ended witha non-zero return code.

The variable command shows the failed command.

System action: Processing of the command stops.

Operator response: Determine why the commandfailed and correct the problem.


ING276E Execution of a service timed out.

Explanation: The return code of the requested serviceindicates a timeout problem.

System action: The requested service does notcomplete successfully.

Operator response: Retry the operation. If theproblem persists, contact your system programmer.

System programmer response: Determine why theservice routine timed out. Examine the NetView log foradditional information.

INGX9701I ingadapter.sh[-](start|stop|generateSampleKeys|IBMSupport|traceON|traceOFF|traceMIN) [suffix]

Explanation: Describes the syntax of the automationadapter start-stop command. It is also shown if thereare invalid arguments or no arguments specified.


Operator response: Specify command syntax asdescribed.

INGX9702I Script ingadapter.sh successfullyfinished processing.

Explanation: Processing of the end-to-end automationadapter script ended successfully.



INGX9703E Script ingadapter.sh terminatedunsuccessfully.

Explanation: An error occurred during scriptexecution.

System action: Script execution is interrupted.

Operator response: Check previous error messages formore details.

INGX9704I Preparing the environment to start theautomation adapter.

Explanation: The script ingadapter.sh performs avalidation and a cleanup step before starting theautomation adapter. The script determines whether anautomation adapter on the same port is alreadyrunning, or if there are any open connections left by afailed automation adapter shutdown. In the former casethe script aborts and in the latter case the connectionsare dropped. Moreover, any existing pid-file of a failedautomation adapter shutdown is deleted.

ING272E • INGX9704I



Operator response: If the automation adapter cannotbe started or the connections cannot be dropped, checkwhether the user ID that was used to run theautomation adapter has the correct access rights. Fordetails see Chapter 8, “Operating the end-to-endautomation adapter,” on page 37.

INGX9705E Cannot start automation adapter withthe same configuration: hostname:port

Explanation: The automation adapter cannot bestarted twice with the same port number and hostnameas specified in the automation adapter masterconfiguration file. This is determined by examining anexisting pid-file whose filename is constructed from thehostname and port number. The containing process-idis used to determine whether another automationadapter is running or if the pid-file has been left overby a failed automation adapter shutdown. If thecorresponding automation adapter USS process doesnot exist then delete the pid file and restart automationadapter. The pid file resides in the automation adapterdata directory with extension '.pid'.


Operator response: Start the automation adapter witha different configuration.

INGX9706I Trying to drop possible open, unusedconnections. Processing port:port_number

Explanation: The script tries to close possible openand unused connections that have been left by a failedautomation adapter shutdown. These connections aredetected with the netstat command. The connectionwill be dropped using the command netstat -d conid,if specific access rights have been granted.

System action: Connections are dropped.

Operator response: If the ingadapter.sh script cannotdrop connections check whether the user ID that wasused to run the automation adapter has the correctaccess rights. For details see Chapter 8, “Operating theend-to-end automation adapter,” on page 37.

INGX9707I Status of the automation adapter:adapter is running.

Explanation: Information about the status of theautomation adapter.



INGX9708I Status of the automation adapter:adapter is not running.

Explanation: Information about the status of theautomation adapter.



INGX9709E Rights to access process list have notbeen granted. Change permissions.

Explanation: The necessary rights to show allprocesses have not been granted to the current user.The script cannot correctly determine the automationadapter status.


Operator response: Change access rights to show allprocesses. For information about this topic see adaptermanual.

INGX9710I Could not retrieve installed codepage.Trying with default codepage:

Explanation: The script was not able to determine theinstalled codepage because environment variable E2Ahas not been set correctly. It attempts to use the defaultcodepage.

System action: The system uses the default codepage.

Operator response: Set the environment variable E2Ato the desired codepage.

INGX9711E The automation adapter configurationfile is missing.

Explanation: The automation adapter masterconfiguration file, ing.adapter{suffix}.properties, was notfound. The suffix is optional and can be specified as thesecond argument of ingadapter.sh.


Operator response: If you use a suffix make sure youhave specified it as the second argument foringadapter.sh. The automation adapter masterconfiguration file is expected to be located in theconfiguration directory. Also check the customizationsection of the script ingadapter.sh. Check manual forcorresponding information.

INGX9712I Generating Sample Keys for testpurposes.

Explanation: The script generates sample keystore andtruststore files for SSL. These keys are for testingpurpose only.



INGX9705E • INGX9712I


|||||||||||||

INGX9713E Keytool was not found. Please install ajava-sdk and customize ingadapter.shaccordingly.

Explanation: The automation adapter script,ingadapter.sh, attempted to use the keytool from theJava SDK but the tool was not found. The keytool isused to generate sample keys for SSL.

System action: Cannot create sample keys.

Operator response: Install a Java SDK and adapt thepath to the keytool using the variable JAVA_KEYTOOLin the customization section of the script ingadapter.sh.

INGX9714I Trace was set to: level.

Explanation: The script has successfully set thespecified level. level is either OFF or DEBUG_MAX.



INGX9715E An error occurred while trying to set loglevel.

Explanation: The script failed in at least one case toset the specified log level. Use the counterpart of thecommand to reset the logger to its previous state.Ignore failures that are reported by the script in thisundo step. Those commands that succeeded the firsttime will succeed in the undo step and those that didnot will not succeed the second time.


Operator response: Undo changes by invoking theopposite trace command: for example, traceOFF iftraceON has failed.

INGX9733I BAD java version foundVersion, required isrequiredVersion

Explanation: The USS script compares the requiredminimum java version with the actual version found byjava version.

System action: Processing terminates.


System programmer response: Install and set up atleast the required java version.

INGX9800E Cannot find message file or message IDfile_or_msgid

Explanation: The message file cannot be loaded or themessage ID cannot be found in the message file.

The variable file_or_msgid shows the name of theassociated message file or ID.


Operator response: Check the class path.


INGX9801E INGXLogger cannot setupcom.ibm.log.PDLogger

Explanation: Initialization of the message and tracelog service failed.

System action: The message or trace data cannot bewritten to the log file.

Operator response: Check the classpath or the loggerconfiguration file, eezjlog.properties.


INGX9802I INGXLogger has successfully beeninitialized using configuration fileconfig_file from path path.

Explanation: Initialization of the message and tracelog service was successful. The logger configurationdata were read from the specified configuration file.

The variable config_file shows the name of theconfiguration file that the logger configuration datawas read from.

The variable path shows the path of theconfiguration file.

System action: Message and trace data will be writtento the log file.



INGX9803E INGXLogger is not available : message

Explanation: An attempt was made to write amessage to the logger but the logger was notinitialized.

The variable message shows the message that couldnot be written to the logger.

System action: The message is written to the stderr.txtfile.

Operator response: None


INGX9810I Timeout after interval seconds.

Explanation: A connection from the JVM to theSA z/OS communication manager (INGPXDST) timedout.

The variable interval shows the duration of thetimeout.

System action: The response from the associatedrequest is not received.

Operator response: Contact your system programmer.



System programmer response: Check the definedtimeout interval for the request. If necessary, increase itas described in “Requests issued by the operationsconsole and the end-to-end automation manager” onpage 69.

INGX9820E JNI function function failed with returncode return_code.

Explanation: A function call to the specified JNI DLLfailed.

v The variable function shows the function call thatfailed.

v The variable return_code shows the return code thatspecifies the reason for the failure:

10 Internal—invalid field ID (attribute not availablein Java class)

20 Internal—handle cannot be saved in Java longsince long too small

21 Internal—handle is invalid, for example, nullpointer

22 Handle cannot be created since no memory

23 Internal—handle iterator already used (numberof slots too small)

25 The ASCB address is no longer correct. Recyclethe End-to-end automation adapter.

26 Internal—invalid array size (Java array size iszero or too small)

27 Internal—invalid object (null pointer or anunexpected class)

30 Internal—invalid parameter (unexpected inputargument)

31 Invalid buffer length (input data buffer hasunexpected length)

32 A Java class that was accessed via JNI hasthrown an exception

33 Creation of a new Java array failed

34 Creation of a new Java string failed

35 Out of memory

36 A Java class cannot be found

40 Catastrophic error—an unexpected exceptionoccurred

1000PPI receive timeout

11nnPPI subsystem not available

12nnPPI initialization of receiver queue failed

13nnThe PPI receiver queue exists already

14nnPPI NetView posted PPI ECB due to subsystemerror

15nnPPI cannot receive data

16nnPPI cannot delete receiver queue

17nnPPI cannot send data

where nn denotes the PPI-specific return code asdescribed in the NetViewApplication Programmer'sGuide, for example:

04 The PPI receiver is not active. For example, theSA z/OS agent is not available or is notproperly customized.

24 The PPI is not active.

25 The automation adapter must be recycled.

26 The receiver program is not defined, forexample, PPI=YES has not been added toINGXINIT.

28 An active subsystem interface address space wasfound, but an active PPI address space was notfound.

32 No NetView storage is available.

35 The receiver buffer queue is full.

System action: The corresponding request failed.

Operator response: Analyze the return code. Ifnecessary, contact your system programmer.

System programmer response: Analyze the returncode. For example:

v RC=1300 indicates that another automation adapteris running on the system. Verify with D OMVS,A=nnnnwhether there is another automation adapterrunning, where nnnn is the ASID of INGE2Exx thatyou obtained with the NetView DISPPI command.

v RC=1726 indicates that there might be a mismatch ofthe XCF group ID in ing.adapter.plugin.properties.Verify whether it matches the XCF group ID that wasdefined in INGXINIT for the automation agent andHSAPRMxx for the automation manager.Alternatively, the statement PPI=YES might bemissing in the INGXINIT member.

INGX9821E Object of class class has already beendestroyed.

Explanation: Internal error.




INGX9820E • INGX9821E


|||

||

INGX9822E Environment error. Check handle failedwith return code return_code.

Explanation: Internal error.




INGX9823E Class class cannot load DLL dll.

Explanation: The JNI DLL cannot be loaded from thespecified Java class.

System action: All communication services will fail.

Operator response: Check the libpath.


INGX9830E INGXStream failed reading from thedata stream. Attempted to read expectedbytes and got actual bytes.

Explanation: The data stream decoder expected toread expected number of bytes but got only actual bytes.

System action: The corresponding request fails.

Operator response: Check why connection wasbroken.


INGX9831E INGXStream failed reading from thedata stream. Found unexpectedend-of-data.

Explanation: The data stream decoder did not find theend-of-data marker. Data might be corrupted. Theconnection might have broken or there is an internaldata stream error.


Operator response: Check why connection wasbroken.


INGX9833E INGXStream failed due to invalidheader.

Explanation: The data stream decoder found aninvalid header in the data stream.




INGX9840E Execution of a remote REXX commandhandler aborted.

Explanation: The corresponding request cannot beexecuted within the SA z/OS NetView backend.


Operator response: Analyze the NetView log for moreSA z/OS messages or REXX syntax errors, or both.


INGX9901E INGXPluginLogger cannot initializecom.ibm.log.EEZLoggerJLog.

Explanation: An attempt to create a logger for theSA z/OS plug-in component was unsuccessful.

System action: No message or trace data is written tothe logger output destination.


INGX9902I INGXPluginLogger has successfullybeen initialized using configuration filefile from path path.

Explanation: The message and trace data of theSA z/OS plug-in will be written to the logger outputdestination.



INGX9904E Adapter plug-in initialization wasunsuccessful.

Explanation: The initialization of the SA z/OS plug-inwas not successful.

System action: Start up of plug-in is stopped.

Operator response: Installation or customization waserroneous, for example, the logger or the plug-inconfiguration file. Also check whether the automationadapter customization for NetView is correct.

INGX9905E Adapter function function failed due toexception from underlying component:exception text

Explanation: The specified adapter plug-in functionwas unsuccessful. An exception was caught from anunderlying component.


Operator response: Read the original exception andfollow its explanation.

INGX9822E • INGX9905E


INGX9906E Error message from SA z/OS: SA z/OSmessage

Explanation: The execution of a command usingSA z/OS was unsuccessful. This message presents theextracted error message.


Operator response: For details about the extractederror message see IBM Tivoli System Automation for z/OSMessages and Codes or Tivoli NetView for z/OS Messagesand Codes.

INGX9907I Adapter plug-in cannot contact theSystem Automation NetView Agent,elapsed time is time seconds.

Explanation: The SA z/OS plug-in detected that asend request failed with message INGX9820E andreturn code 1704 and this error situation cannot beresolved within certain time period. It is assumed thatthe SA z/OS NetView Agent is no longer available.

System action: The adapter stops intentionally.

Operator response: Restart the SA z/OS NetViewAgent. See also the TIMEOUT_SA_NOTAVAILparameter in the plug-in configuration file.

INGX9910I The command cmd will be performedfor resource res on behalf of user usrwith comment: cmt

Explanation: A user has issued a command thatrelates to a resource. This command has been receivedby the adapter and will be performed by automationon the indicated resource.

The variable cmd shows the end-to-end commandthat was issued against the adapter.

The variable res shows the name of the SA z/OSresources.

The variable usr shows the end-to-end operatorname that issued the command.

The variable cmt shows the comment that wasentered by the operator.

System action: The command has been received andwill be executed for the resource.


INGX9911I The command cmd will be performedfor system sys on behalf of user usr

Explanation: A user has issued a command thatrelates to a system. This command has been receivedby the adapter and will be performed by automationon the specified system.

The variable cmd shows the end-to-end commandthat was issued against the adapter.

The variable sys shows the name of the system thatis involved with the command.


System action: The command has been received andwill be executed.


INGX9912I The command to move resource groupgrp away from system sys will beperformed on behalf of user usr withcomment: cmt

Explanation: A user has issued a request to move aresource group away from specified system. Thiscommand has been received by the adapter and will beperformed by automation.

The variable grp shows the name of the group thatis involved with the command.






INGX9913I The command to move resource groupgrp to the home system will beperformed on behalf of user usr withcomment: cmt

Explanation: A user has issued a command thatrelates to a resource. This command has been receivedby the adapter and will be performed by automationon the indicated resource.






INGX9914I The command to move resource groupgrp to system sys will be performed onbehalf of user usr with comment: cmt

Explanation: A user has issued a command thatrelates to a resource. This command has been received



by the adapter and will be performed by automationon the indicated resource.







INGX9915I Command reset from non-recoverableerror will be performed on resource reson behalf of user usr

Explanation: A user found a non-recoverable resource,which means the resource is not automated until a userissues the reset command. The reset command has beenreceived by the adapter and will be performed byautomation on the indicated resource.

The variable res shows the name of the SA z/OSresources.


System action: The command has been received andwill be executed for the resource.


INGX9915I


Appendix D. Notices

This information was developed for products and services offered in the US. Thismaterial might be available from IBM in other languages. However, you may berequired to own a copy of the product or product version in that language in orderto access it.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785US

For license inquiries regarding double-byte character set (DBCS) information,contact the IBM Intellectual Property Department in your country or sendinquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer ofexpress or implied warranties in certain transactions, therefore, this statement maynot apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided forconvenience only and do not in any manner serve as an endorsement of those


websites. The materials at those websites are not part of the materials for this IBMproduct and use of those websites is at your own risk.

IBM may use or distribute any of the information you provide in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785US

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

The performance data and client examples cited are presented for illustrativepurposes only. Actual performance results may vary depending on specificconfigurations and operating conditions.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

Statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to actual people or business enterprises is entirelycoincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment to


IBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. The sampleprograms are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work must include a copyright notice as follows:© (your company name) (year).Portions of this code are derived from IBM Corp. Sample Programs.© Copyright IBM Corp. _enter the year or years_.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the web at "Copyright andtrademark information" at www.ibm.com/legal/copytrade.shtml.

Terms and conditions for product documentationPermissions for the use of these publications are granted subject to the followingterms and conditions.

Applicability

These terms and conditions are in addition to any terms of use for the IBMwebsite.

Personal use

You may reproduce these publications for your personal, noncommercial useprovided that all proprietary notices are preserved. You may not distribute, displayor make derivative work of these publications, or any portion thereof, without theexpress consent of IBM.

Commercial use

You may reproduce, distribute and display these publications solely within yourenterprise provided that all proprietary notices are preserved. You may not makederivative works of these publications, or reproduce, distribute or display thesepublications or any portion thereof outside your enterprise, without the expressconsent of IBM.

Rights

Except as expressly granted in this permission, no other permissions, licenses orrights are granted, either express or implied, to the publications or anyinformation, data, software or other intellectual property contained therein.

IBM reserves the right to withdraw the permissions granted herein whenever, in itsdiscretion, the use of the publications is detrimental to its interest or, asdetermined by IBM, the above instructions are not being properly followed.

Appendix D. Notices 105

http://www.ibm.com/legal/us/en/copytrade.shtml

You may not download, export or re-export this information except in fullcompliance with all applicable laws and regulations, including all United Statesexport laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESEPUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUTWARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDINGBUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.


Index

AAdapterJoinEvent 61additional information, automation

domain 65advanced automation option

AOF_E2E_EAS_PPI 20, 57AOF_E2E_EVT_RETRY 20AOF_E2E_EXREQ_NETLOG 20AOF_E2E_TKOVR_TIMEOUT 20customizing 20INGREQ_PRI.E2EMGR 20, 71setting request priority 71setting the PPI receiver ID 57

AOF_E2E_EAS_PPI advanced automationoption 20

AOF_E2E_EVT_RETRY advancedautomation option 20

AOF_E2E_EXREQ_NETLOG advancedautomation option 20

AOF_E2E_TKOVR_TIMEOUT advancedautomation option 20

AOF233E message, diagnosing domaininitialization failure 55

AOFEXE2E sample exit and overwritingcommands 71

application definitionautomation adapter 46event/automation service 45

authentication 29authentication checking 33authentication, operator 23authorization checking 33authorization exit 33authorization user exit, sample 34Auto Operators entry type 8, 19automated applications defined to

SA z/OS 43automated function 25, 61automated operator functions 19

and concurrent working threads 19defining 8, 19EVTOPER, checking status 55

automation adapterapplication definition 46asynchronous communication 5communication 3communication flow 23configuration files 23configuring 23customizing 23dependencies 13event/automation service 5failover to a backup system 43grouping considerations 43high availability 41host name 23, 61host name port 61ingadapter.sh 27initial contact timeout interval 61initial contact with end-to-end

automation server 61

automation adapter (continued)introduction 1, 2IP address 23, 61IP address port 61Java Virtual Machine access 23master configuration file 23messages 81MOVE group definition 53non-disruptive recovery from

errors 41operating 37plug-in domain name 25, 61plug-in, messages 89prerequisites 13problem determination 55program-to-program interface 4purpose and rules 41quick startup 7recycling after stopping NetView 60recycling after stopping SSI

subsystem 60recycling in the same system 42remote contact activity interval 61restart 43resynchronization of 42security 33start-stop script 27start-stop script, and SSL

configuration file 27start-stop script, using 37startup using INGXADPT 11stop delay 61synchronous communication 4TCP/IP port relationship 23two in same sysplex 5

automation agent, primary 5automation domain

additional information 65general information 65policy information 65remaining offline after error

recovery 60automation manager status 76

mapping to resource data modelstatus 76

automation manager, problem withautomation domain after restarting 60

automation policy, defining 44AUTOPFN parameter, description 61

Bbackup system, failover of the

automation adapter to 43bound socket, dropping with

NETSTAT 58buffer queue limit

description 25, 61

CCEE3501S error message, and link list

errors 58certificate alias name 61certificates 27cfgeezdmn

System Automation ApplicationManager utility 28

CHECK_HEALTH function failure 60code page, Java 61CODEPAGE parameter, description 61commands, overwriting for resource

objects 71common global variable

customizing 20INGREQ_PRI.E2EMGR 71setting request priority 71

communicationautomation adapter, asynchronous 5automation adapter, introduction 3automation adapter, synchronous 4event/automation service 5program-to-program interface 4

communication flow, automationadapter 23

concurrent working threads 61and automated operator functions 19

configuration fileexample plug-in 25JAAS 29Java logger 30master 23plug-in 25SSL 27

configuration files 23configuring

automation adapter 23Custom-Root directory 14customizing

advanced automation options 20automation adapter 23UNIX System Services 31

Ddefining

application for event/automationservice 45

application for the automationadapter 46

automated operator functions 8, 19automation policy 44E2EOPER automated function 19MOVE group for the automation

adapter 53delaying the stopping of the automation

adapter 61DISPAOPS command response 55DISPPI command, using for problems

with program-to-program interface 56


domain initialization failure,diagnosing 55

domain object 65domain state 65dropping bound socket with

NETSTAT 58DSIPARM data set

customizing 8

EE2EOPER automated function,

defining 19eez-initial-contact parameter,

description 61eez-initial-contact-retry-interval-minutes

parameter, description 61eez-max-connections parameter,

description 61eez-operator-authentication

parameter 33eez-operator-authentication parameter,

description 61eez-plugin-classpath parameter,

description 61eez-remote-contact-activity-interval-

seconds parameter, description 61eez-remote-contact-hostname parameter,

description 61eez-remote-contact-over-ssl parameter,

description 61eez-remote-contact-port parameter,

description 61eez-ssl-keystore parameter,

description 61eez-ssl-keystorealias parameter,

description 61eez-ssl-keystorepassword parameter,

description 61eez-ssl-truststore parameter,

description 61eez-stop-delay parameter, description 61EEZA0001E 81EEZA0002E 81EEZA0003E 81EEZA0004E 81EEZA0006E 81EEZA0007E 81EEZA0008E 81EEZA0009E 81EEZA0010E 82EEZA0011E 82EEZA0012E 83EEZA0013E 83EEZA0014E 83EEZA0015E 83EEZA0017E 83EEZA0022E 83EEZA0023E 83EEZA0024E 83EEZA0025E 83EEZA0026E 83EEZA0027E 83EEZA0028E 84EEZA0029E 84EEZA0030E 84EEZA0031E 84

EEZA0032E 84EEZA0033E 84EEZA0036E 84EEZA0037E 84EEZA0038E 84EEZA0039E 84EEZA0040E 85EEZA0041E 85EEZA0042E 85EEZA0043E 85EEZA0045E 85EEZA0047E 85EEZA0051W 85EEZA0052E 85EEZA0053E 85EEZA0055E 86EEZA0056I 86EEZA0057E 86EEZA0058E 86EEZA0059E 86EEZA0060I 86EEZA0061E 86EEZA0061E messaage 58EEZA0062I 86EEZA0063I 87EEZA0064I 87EEZA0070E 87EEZA0071E 87EEZA0100I 87EEZA0101I 87EEZA0102I 87EEZA0103I 87EEZA0104I 87EEZA0105I 87EEZA0111I 87EEZA0112I 88EEZA0113I 88EEZA0114I 88EEZA0115I 88EEZA0116I 88EEZA9991E 88EEZA9992E 88EEZAdapterDefaultLogin 33EEZC0001I 88EEZC0002I 88EEZC0003I 88EEZC0004I 89EEZK0003E 89EEZK0004E 89EEZK0005E 89EIF cache directory 61EIF caching, switching on and off 61EIF receive host name 61EIF receive port 23, 61EIF send host name 23, 61EIF send port 61EIF socket reconnect interval 61eif-cache parameter, description 61eif-cache-size parameter, description 61eif-receive-from-hostname parameter,

description 61eif-receive-from-port parameter,

description 61eif-retry-interval-seconds parameter,

description 61eif-send-to-hostname parameter,

description 61

eif-send-to-port parameter,description 61

end-to-end automationlimitations 54login module 29Operations Console 65resource data model 65

end-to-end automation adapterstartup using INGXADPT 11

end-to-end automation management,introduction 1

end-to-end automation managerrequests, overruling hold flag for 72

end-to-end automation manager, requestsissued by 69

end-to-end automation server, initialcontact by automation adapter 61

Environment variables 13error recovery, automation domain

remaining offline after 60errors

link list 58non-disruptive recovery from 41

event log file 30event/automation service 17

application definition 45communication with automation

adapter 5configuring the global initialization

file 18customizing the sample

procedure 17problems, using MODIFY command

for 56event/automation service, starting 17EVTOPER automated operator function,

checking status 55example plug-in configuration file 25examples of RACF profiles 35

Ffailover of the automation adapter to a

backup system 43functions, automated operator 19

GgenerateSampleKeys parameter, of

ingadapter.sh start script 38Global initialization file (IHSAINIT) 18graphical user interface 30group ID in INGXINIT 25, 61grouping considerations for the

automation adapter 43GRPID parameter

description 61

Hhigh availability, automation adapter 41hold flag, disregarding 72host name

automation adapter 23, 61EIF receive 61EIF send 23, 61


IIBMSupport parameter, of ingadapter.sh

start script 38IHSAEVNT 17IHSAMCFG 18ing.adapter.properties file 23ING008I message and automation

domain timeout 60ING230E 89ING231E 89ING232I 89ING233E 90ING234E 90ING235W 90ING235W message and automation

domain timeout 60ING236W 90ING237W 90ING238E 90ING239W 91ING240E 91ING241E 91ING242E 92ING243E 92ING244E 92ING245E 92ING246E 92ING247E 92ING248E 92ING249E 92ING250E 93ING251E 93ING252E 93ING253E 93ING254E 93ING255E 93ING256E 93ING257E 94ING258E 94ING259E 94ING260E 94ING261E 94ING262W 94ING263E 94ING264E 94ING265E 95ING266E 95ING267E 95ING268E 95ING269E 95ING270E 95ING271E 95ING272E 96ING273W 96ING274E 96ING275E 96ING276E 96ING276E message and automation

domain timeout 60ingadapter.sh shell script

and nohup command 38and SSL configuration file 27parameters 38prerequisites 37syntax 38using 37

INGAMS command, using to checkprimary NetView agent 56

INGE2E command 72INGE2E PREPARE command 9INGE2E RESYNC command and

automation domain timeout 60INGE2E Verify command 12INGEVOBS command, using to check

end-to-end automation registrationconsumer registration, checking with

INGEVOBS command 57INGEVOBS LIST command response 57INGPXDST communication task

problem with automation domainafter restarting 60

INGREQ_PRI.E2EMGR advancedautomation option 20

INGREQ_WAIT common global variable,setting timeout with 60

INGX9701I 96INGX9702I 96INGX9703E 96INGX9704I 96INGX9705E 97INGX9706I 97INGX9707I 97INGX9708I 97INGX9709E 97INGX9710I 97INGX9711E 97INGX9712I 97INGX9713E 98INGX9714I 98INGX9715E 98INGX9733I 98INGX9800E 98INGX9801E 98INGX9802I 98INGX9803E 98INGX9810I 98INGX9820 message and recycling

automation adapter 60INGX9820E 99INGX9821E 99INGX9822E 100INGX9823E 100INGX9830E 100INGX9831E 100INGX9833E 100INGX9840E 100INGX9901E 100INGX9902I 100INGX9904E 100INGX9905 message and recycling

automation adapter 60INGX9905E 100INGX9906E 101INGX9907I 101INGX9910I 101INGX9911I 101INGX9912I 101INGX9913I 101INGX9914I 101INGX9915I 102INGXADPT 9, 39

starting up end-to-end automationadapter 11

INGXINIT 19PPI setting 8

INGXINIT initialization membercustomizing 8

INGXINIT, group ID 25, 61initial contact, automation adapter

timeout interval 61with end-to-end automation

server 61Install-Root directory 14introducing the automation adapter 1IP address

automation adapter 23, 61master configuration file 23

JJAAS configuration file

end-to-end automation loginmodule 29

overview 29sample 29z/OS login module 29

JAAS login module 33Java

classpath and security 61code page 61JIT compiler, and USS problems 60loading DLLs, problems with 60logger configuration file 30system properties, and SSL

configuration file 27Java Runtime

setting up 13Java Virtual Machine 23

Kkeyboard xiiikeystore 27

creating for use by SSL 29keystore file, password 61keystore filename 61keystore password

encrypting, using cfgeezdmn 28

Llimitations to end-to-end automation 54log file

event 30message 30trace 30

logger configuration file, Java 30login module

end-to-end automation 29JAAS 29z/OS 29

Mmaster configuration file

introduction 23IP addresses 23parameters 61

Index 109

master configuration file (continued)sample 23

message log file 30messages

AOF233E and domain initializationfailure 55

automation adapter 81automation adapter plug-in 89CEE3501S and link list errors 58ING008I and automation domain

timeout 60ING235W and automation domain

timeout 60ING276E and automation domain

timeout 60INGX9820 and recycling automation

adapter 60INGX9905 and recycling automation

adapter 60MODIFY command, for problems with

event/automation service 56MOVE group definition for the

automation adapter 53MVS MODIFY command, for problems

with event/automation service 56

NNETSTAT command, using to drop

bound socket 58NetView

checking primary agent withINGAMS 56

event/automation service 17event/automation service,

enabling 11event/automation service, problems

with 56event/automation service,

verifying 12operator task name 25, 61PIPE default safe 33planned outages 54stopping, recycling automation

adapter after 60NetView message adapter service 18

configuring 18NetView SSI JCL procedure 10node, general information 67nohup command, and ingadapter.sh start

script 38non-disruptive recovery from errors 41

Ooffline, automation domain remaining

after error recovery 60online, switching automation domain to

after error recovery 60operating the automation adapter

as a SA z/OS defined resource 40from USS console 37with customizable procedure,

INGXADPT 9, 39operations console

requests issued by 69

operator authentication 23operator task name, NetView 25, 61overruling hold flag for end-to-end

automation manager requests 72overwriting commands, for resource

objects 71

Pparameters

AUTOPFN 61CODEPAGE 61eez-data-directory 61eez-initial-contact 61eez-initial-contact-retry-interval-

minutes 61eez-max-connections 61eez-operator-authentication 33, 61eez-plugin-classpath 61eez-remote-contact-activity-interval-

seconds 61eez-remote-contact-hostname 61eez-remote-contact-over-ssl 61eez-remote-contact-port 61eez-ssl-keystore 61eez-ssl-keystorealias 61eez-ssl-keystorepassword 61eez-ssl-truststore 61eez-stop-delay 61eif-cache 61eif-cache-size 61eif-receive-from-hostname 61eif-receive-from-port 61eif-retry-interval-seconds 61eif-send-to-hostname 61eif-send-to-port 61GRPID 61master configuration file 61plug-in configuration file 61plugin-configfile-sa4zos 25, 61plugin-domain-name 61PPIBQL 61SSL configuration file 61TIMEOUT 61TIMEOUT_SA_NOTAVAIL 61

password 33plug-in configuration file

example 25introduction 25name, setting 61parameters 61

plug-in domain name 25, 61plugin-configfile-sa4zos parameter,

description 25, 61plugin-domain-name parameter,

description 61policy information, automation

domain 65port

automation adapter host name 61EIF receive 23, 61EIF send 61

PPIenabling for the NetView subsystem

interface address space (SSI) 10PPI buffer queue limit 25, 61

PPI communicationsetting in INGXINIT 8

PPI queue, number of elements 25, 61PPIBQL parameter

description 61prerequisites for UNIX System

Services 37prerequisites, automation adapter 13primary automation agent 5primary NetView agent, problems

selecting 56problem determination

automation domain remaining offlineafter error recovery 60

consumer registration 57domain initialization failure 55introduction 55link list errors 58NetView event/automation

service 56program-to-program interface 56selecting the primary agent 56TCP/IP bind socket 58timeout of requests 59

profileRACF 34, 35RACF, examples of 35

program-to-program interface, problemswith 56

QQuick startup

automation adapter 7

RRACF 29, 33

profile 34, 35profile, examples 35

reconnect interval, EIF socket 61recycling the automation adapter in the

same system 42REFRESHSTART STARTUP policy and

CHECK_HEALTH function failure 60relations to resource objects 68relationship, TCP/IP port and automation

adapter 23remote contact activity interval 61request mapping to SA z/OS commands

for resource objects 69request priority, for resource objects 71requests

issued by end-to-end automationmanager 69

issued by operations console 69issued to resource objects 69overruling hold flag for 72overwriting commands from 71timeout problems with 59

resource data displayed by WebUI 65resource data model

automation domain, additionalinformation 65

automation domain, policyinformation 65


resource data model (continued)compound status 78domain object 65domain state 65node 67node, general information 67operational state 78relations to resource objects 68request mapping to SA z/OS

commands 69resource object 67resource object, additional

information 67resource object, general

information 67resource object, overwriting

commands for 71resource object, relationships

information 68resource object, request priority 71resource object, requests issued to 69status 76status mapping 76status mapping rules 76status mapping steps 76top level resource 68WAIT parameter 69

resource objectadditional information 67general information 67overwriting commands for 71relations to 68relationships information 68request mapping to SA z/OS

commands 69request priority 71requests issued to 69

restart of the automation adapter 43resynchronization of the automation

adapter 42

SSA z/OS initialization member

ING.DSIPARM (INGXINIT) 19sample authorization user exit 34sample master configuration file 23security

authorization exit 33automation adapter 33JAAS configuration file 29Java classpath 61keystore and truststore for use by

SSL 29keystore password 28NetView PIPE default safe 33password 33RACF profiles 35SSL configuration file 27user ID 33

settingrequest priority for resource

objects 71timeout with INGREQ_WAIT common

global variable 60shortcut keys xiiisocket connection 61

socket, binding problem 58SSI subsystem

stopping, recycling automationadapter after 60

SSL configuration filecertificate alias name 61example 27Java system properties 27keystore file, password 61keystore filename 61missing parameters 27parameters 61truststore filename 61

SSL socket connection 61start parameter, of ingadapter.sh start

script 38start-stop script

JAAS option 29using 37

status mappingfor problem SA z/OS compound

status 78introduction 76rules 76steps 76

stop parameter, of ingadapter.sh startscript 38

subplex, XCF group ID 25, 61switching on and off EIF caching 61System Automation Agent

customizing 19

TTCP/IP bind socket problem 58TIMEOUT parameter, description 61TIMEOUT_SA_NOTAVAIL parameter,

description 61top level resource 68trace log file 30traceMIN parameter, of ingadapter.sh

start script 38traceOFF parameter, of ingadapter.sh start

script 38traceON parameter, of ingadapter.sh start

script 38truststore

creating for use by SSL 29truststore file 27truststore filename 61

UUNIX System Services 9, 10

automatic configuration 9console 37, 39Custom-Root directory 14customizing 31default file system 14Install-Root directory 14manual configuration 10prerequisites 37problems loading DLLs 60setting up environment variables 13shared file system 16writing to stdout and stderr files 60

user ID 33USS 31

WWAIT parameter, for SA z/OS

commands 69WebSphere authentication and end-to-end

automation login module 29WebUI

resource data displayed by 65

XXCF group ID 25, 61

Zz/OS login module 29

Index 111


IBM®

Printed in USA

SC34-2750-01

Documents

System Automation for z/OS: End-to-End Automation Adapter · The System Automation for Application Manager library The following table shows the information units in the System Automation