ZAC 4.4 Installation Guide

Revision Date: June 23, 2021

Table of Contents 

1 About this document

1.1 Intended Audience

1.2 Terminology

2 Summary of changes

2.1 Summary of changes in V4.4.00

2.1.1 General changes

2.1.2 Parameters changes

2.1.3 Commands changes

2.1.4 Reporting changes

2.1.5 Alerts Changes

2.1.6 SMF Changes

2.1.7 Messages

3 ZETALY Automated Capacity© overview

3.1 ZETALY Automated Capacity© environment

3.1.1 Collection environment

3.1.2 Setting environment

3.1.3 Network environment

3.2 ZETALY Automated Capacity© architecture

3.2.1 General architecture

3.2.2 ZETALY Automated Capacity© typical configuration sample

4 Installing ZETALY Automated Capacity©

4.1 Installing ZETALY Automated Capacity© in z/OS

4.1.1 Restoring of ZAC delivered files (required)

4.2 Installing ZETALY Automated Capacity© for the first time

4.2.1 Customizing the installation file (required)

4.2.2 Installing ZETALY Automated Capacity© Monitor

4.2.3 Installing ZETALY Automated Capacity© Reporting web server

4.2.4 Installing ZETALY Automated Capacity© Collector

4.3 Migrating ZETALY Automated Capacity©

4.3.1 Dismount Backup ZFS file

4.3.2 Migrate ZAC parmlib members

4.3.3 Define new ZAC commands authorization profiles

4.4 Starting / Stopping ZETALY Automated Capacity©

4.4.1 Starting the Monitor

4.4.2 Stopping the Monitor

4.5 Starting /Stopping Web Reporter

4.5.1 Starting the Reporter using a Domino web server

4.5.2 Starting the Reporter using an APACHE web server

4.5.3 Verifying that web reporting is operational

4.5.4 Stopping the Reporter using a Domino web server

4.5.5 Stopping the Reporter using the APACHE web server

4.6 Starting /Stopping ZAC Collector

4.6.1 Starting the ZAC Collector

4.6.2 Stopping the ZAC Collector

4.7 Testing ZAC collector

Messages and codes

5.1 Messages and codes table

5.1.1 ASCxxxxx messages

5.1.2 HMCxxxxx messages

6 Enabling communication with BCPii

6.1 ZETALY Automated Capacity© architecture sample using BCPii

6.2 Enable BCPii communication on the SE

6.3 Define BCPii community name on the SE

6.4 Set BCPii permissions in HMC as of Z14

6.5 Define BCPII general SAF authority

6.6 Startup and shutdown BCPii

6.7 Testing the BCPii communication

7 Enabling communication with the HMC

7.1 ZETALY Automated Capacity© architecture sample with the HMC API

7.2 Configuring the firewall (optional)

7.3 Configuring the HMC API (SETMETHOD=HMC)

7.3.1 Detailed procedure to configure the console for API support

7.4 Testing the HMC API and communication

7.5 HMC communication troubleshooting

7.6 Behavior of ZETALY Automated Capacity© during a communication problem with the HMC

8 Managing LPARs with ZETALY Automated Capacity©

8.1 Warning about HMC use

8.2 IPL & LOAD method

1 About this document

The information contained in this document is subject to modification without prior notice and does not engage the liability of ZETALY® in any way. The software described in this document is provided within the terms of a software license agreement.
The reproduction or transmission of this manual even partly and in whatever form, is forbidden without the express written authorization of ZETALY®.
The trademarks and the names quoted in this manual belong to their respective owners.
© Copyright ZETALY® 2006−2021

1.1 Intended Audience

This document is intended for:

• People involved in System z installation, configuration and tuning;
• System z security professionals, including I/T and I/S managers;
• Systems planners, analysts, integrators, and administrators.

1.2 Terminology

This chapter defines technical terms and abbreviations used in this document.

Table 1 Abbreviations and technical terms definition 

2 Summary of changes

2.1 Summary of changes in V4.4.00

Previous release was V4.3.00

2.1.1 General changes

• Adding of container management feature;
• Follow-up of CMP/CPCs and LPARS Monthly cumulated MSUs consumption.
• Parallelism in BCPII settings requests
• BCPII timeout control

2.1.2 Parameters changes

2.1.2.1 New ASCCTNxx parameters member to describe containers

2.1.2.2 GENERAL parameters changes

• New parameters to control BCPII settings parallelism and timeout.

2.1.2.3 LPAR parameters changes

2.1.2.4 NoneALERT parameters changes

• A lot of new variable have been added in Alert process in V4.3 and V4.4
• New Containers type rules have been added.

2.1.3 Commands changes

• Parameters management commands have been updated to take containers parameters into account.

2.1.4 Reporting changes

• New graphs to display containers consumption; • New graphs to follow Monthly cumulated MSUs.

2.1.5 Alerts Changes

• New fields available about cumulated consumptions
• New fields available about containers consumptions

2.1.6 SMF Changes

• Added Monthly cumulated MSUs consumptions information in subtypes 01, 02, 03
• Added Tenant resource groups consumption information in subtype 02;
• Added Containers parameters information in subtype 04;
• Added Containers consumption information in a new subtype 05.

2.1.7 Messages

• Messages ASCnnnnx, and HMCnnnnx are explained in a separate document. Refer to ZAC-MCR4300-nn-E documentation for more information.

3 ZETALY Automated Capacity© overview

This chapter presents ZETALY® product ZETALY Automated Capacity©, version 4.4.00. 

3.1 ZETALY Automated Capacity© environment

3.1.1 Collection environment

ZAC Collector 

ZETALY Automated Capacity© collects metrics using its own collector (ASC). One ZAC collector STC must be started on every z/OS image.

ZAC Monitor 

At each interval (the running frequency of the algorithm – the Policy Adjustment of ZAC), the ZAC Monitor retrieves data from ZAC Collectors such as R4H, DC, IMSU, Weight, number of logical processors, WLM Capping percentage for each LPAR and serial number, family, type, number of CPs for each CPC. In addition, the ZAC collector provides WLM service class and tenant resource groups information.

3.1.2 Setting environment

At each interval (the running frequency of the algorithm), ZAC decides to change (or not) the z/OS image defined capacity (DC). There are 2 ways to execute those changes:

BCPii 

• The BCPii feature is available on z/OS 1.11 and higher

HMC API 

• Configure the API and allow the HMC to be accessed via the network

3.1.3 Network environment

If you plan to use BCPii setting method, there are no network prerequisites.

If you plan to use HMC setting method, ask your Network Specialist for routing availability between the various z/OS images, and between ZETALY Automated Capacity© z/OS images and the HMC.

If a Firewall is used, make sure the SNMP protocol is opened between ZETALY Automated Capacity© z/OS images and the HMC.

More information is available in chapter 7: “Enabling communication with the HMC”.

3.2 ZETALY Automated Capacity© architecture

3.2.1 General architecture

The ZETALY Automated Capacity© product consists of three parts:

• The “Monitor” (main STC) controls the entire process. It runs permanently on one LPAR and executes cyclically (the frequency depends on the “INTERVAL” parameter);
• The “Collectors” which are ZAC agents (collector STC);
• The “Reporter” (HTTP server STC), which allows access to graphs and tables via a web browser
• Internet explorer 11. Recommended version is IE 11
• Mozilla Firefox 42+
• Google Chrome 30+

Each cycle collects data, analyses LPAR behavior, sets LPAR capacity (or not), updates report files, sends alarms (or not) and writes SMF records.

Figure 1 ZAC Architecture

3.2.2 ZETALY Automated Capacity© typical configuration sample

• One ZAC monitor (ZCASC) for two CPCs. This example shows one monitor, which manages two CPCs (a maximum of eight CPCs can be managed by one monitor).

Another way is to start one monitor per CPC. Thus, when you stop the monitor, only one CPC and the LPARs belonging to it are impacted.

In CMP mode you must start only one monitor to manage the entire CMP.

• One ZAC Web Reporter (ZCASCW) per ZAC monitor
• One ZAC Collector (ZCASCCOL) per LPAR managed by the ZAC monitor

Figure 2 Typical ZAC Configuration 

4 Installing ZETALY Automated Capacity©

4.1 Installing ZETALY Automated Capacity© in z/OS

The installation process consists of:

• Restoring all ZAC delivered files;
• Setting values for installation parameters;
• Customizing installation jobs;
• Executing installation jobs and operations.

There are two kinds of installation: new installation “from scratch”, and migration from a previous version of ZETALY Automated Capacity©. In both cases, you must customize the SAMPLIB dataset, which will contain installation jobs and tools. 

In the case of a migration, you also must customize the MIGRATE dataset, which will contain migration jobs.

4.1.1 Restoring of ZAC delivered files (required)

4.1.1.1 Zip file contents

ZCOST.ASCVnnnn.Lvvvvvvv.DUMP.zip file includes the

ZCOST.ASCVnnnn.Lvvvvvvv.DUMP.XMI file. This file contains an ADRDSSU DUMP of the following files:

• ZCOST.ASCVnnnn.LEVELS Delivery Levels summary (Information only)
• ZCOST.ASCVnnnn.INSTDOC Quick install guide
• ZCOST.ASCVnnnn.LOADLIB Load modules library
• ZCOST.ASCVnnnn.HTM Html install files
• ZCOST.ASCVnnnn.INSTALL Installation & sample JCLs
• ZCOST.ASCVnnnn.PARMLIB Parmlib members raw samples
• ZCOST.ASCVnnnn.ZFS Main ZFS file (programs, images…)

4.1.1.2 Restore ZAC files

4.1.1.2.1 Extract ZIP file (required)

Extract (unzip) the delivered dump file ZCOST.ASCVnnnn.Lvvvvvvv.DUMP.zip described above User Action: Manually unzip the file on your PC

JOB: None

Result: you obtain the following file: ZCOST.ASCVnnnn.Lvvvvvvv.DUMP.XMI

Return code: N/A

Restart: N/A

Remarks: None.

4.1.1.2.2 Upload XMI file (required)

Upload ZCOST.ASCVnnnn.Lvvvvvvv.DUMP.XMI to z/OS using FTP or IND$FILE. User Action: 1 -Allocate target file using job sample below.

2 -Manually upload the unzipped dataset into the pre-allocated target dataset. USE FTP or TSO IND$FILE method, binary type (no CRLF or ASCII translation).

Return code: N/A

Restart: Delete pre-allocated file.

Remarks: The target file is a "TSO XMIT" formatted file.

4.1.1.2.3 Receive DUMP file (required)

In your TSO environment, issue the RECEIVE command to extract the "xmi" file.

User Action: You may either use TSO receive command in prompt mode or use the sample job below to receive dump "xmi" file.

Manually customize the job (target_name, DDIN, DATASET) and submit it.

Return code: N/A

Restart: At the beginning of the job.

Remarks: None.

4.1.1.2.4 Restore ZAC files from DUMP file (required)

Restore the files from &hlq..ASCVnnnn.Lvvvvvvv.DUMP using ADRDSSU.

User Action: Manually customize sample job below (DUMPIN, hlq, OUTVOL) and submit it.

Return code: 0

Restart: Delete previously restored files.

Remarks: Main ZFS file is restored.

4.2 Installing ZETALY Automated Capacity© for the first time

Once all delivered files are restored, you may use the hlq.ASCVnnnn.INSTDOC restored file as a guide to perform standard quick installation. This file is a PDS containing one member per step of the installation. The steps are named accordingly to the order they must be executed. Each member describes briefly the process, the action to do by the installer and the expected result of the step.

If necessary, to obtain more details about installation steps, refer to the process documentation below.

4.2.1 Customizing the installation file (required)

In this process, you will choose the values of all installation parameters and execute a job that generates a SAMPLIB library, which will contain all customized installation jobs.

4.2.1.1 Update $INSTPRM member

Update $INSTPRM member in the ZAC INSTALL library accordingly to your environment.

In this member, you must provide all the values required to customize SAMPLIB JCLs. All the values originally set are the default installation values.

Considerations about Installation paths 

Installation paths names are very important. They are used to access programs, to communicate with the HMC, to access current and backup HTML pages, and data of the HTTP server. There are three installation paths: 

• The main install path (path, used to access programs icons and images);
• The web installation path (pathweb, used to define where reporting data will be stored);
• The backup installation path (pathbkp, used to define where archived reporting data will be stored). Define installation paths: 
• The three installation paths are explicitly provided in a special file that must be defined in the monitor STC using the DDNAME PATH. This file may contain three records as follows:

path=/ascpgm Required. This is the main path pathweb=/ascweb Required. pathbkp=/ascbackup Required.

The default installation path name delivered in the installation package are /u/asc/pgm, u/asc/web and u/asc/backup.

You may change them accordingly to your standards.

4.2.1.2 Generate customized installation jobs

Submit $ASCUSTM job from ZAC INSTALL library. This Job will create and customize the SAMPLIB library, where all jobs required for the installation will be located.

4.2.2 Installing ZETALY Automated Capacity© Monitor

All required installation jobs are located in the customized SAMPLIB library.

There are three parts in ZETALY Automated Capacity© which are managed by three Started Tasks.

• The Monitor (Main STC)
• The ZAC Agents (Collector STC)
• The Web reporter (Http Server STC)

Monitor, Collector agents and reporter are always required.

4.2.2.1 Define the RESTART Dataset

ZETALY Automated Capacity© is designed to allow for restarting in “WARM mode”. This feature requires storing the “restart” data into a file used at restart time. Review and submit ALLORDS job of the SAMPLIB.

4.2.2.2 Define ZFS Files

ZAC uses 3 ZFS (HFS) files to store reports elements.

• The main ZFS file contains ZAC programs and elements requested to navigate in reports. It is provided.
• The Web ZFS file, contains current web reports. It is not provided; you must create it.
• The Backup ZFS file, contains archived reports. It is not provided; you must create it.

4.2.2.2.1 Define ZFS File for Web Reports

The ZFS file, which will contain current web reports, is not provided in the ZAC package; you must define your own allocated space. The size of your current reports depends on the number of reported objects (CPCs, LPARs, SYSPLEX, WLM Service Classes) and on the depth of the reporting (see ASC REPORTDEPTH parameter). On an indicative basis, the size will use 1000 k-bytes as fixed, 50 k-bytes per LPAR, 100 k-byres per container, plus 10 k-bytes per service class defined in the LPAR, 30 k-bytes per LPAR in a group, to store 24 hours depth data.

For example, if your ZAC manages 20 LPARs with an average of 20 Service Classes per LPAR, and 5 LPARs in groups, and your report depth is 36 hours, your current reports will use approximatively: (1000 + 50*20 + 10*20*20 +30*5) * 36/24 = 9 225 k-bytes.

Review and submit ZFSWEBAL job of the SAMPLIB.

4.2.2.2.2 Define ZFS File for Archived Reports

The ZFS file, which will contain archived reports, is not provided in the ZAC package; you must define your own allocated space. The size of your archived reports depends on the number of reports you plan to keep. Each archived report will require the same size than the current report to archive. See details for size calculation in previous chapter 4.2.2.2.1 Define ZFS File for Web Reports. Review and submit ZFSBKPAL job of the SAMPLIB.

4.2.2.3 Set APF Authorization for ZETALY Automated Capacity© Loadlib

Static Definition 

Create or modify PROGxx in your PARMLIB.

Define the ZETALY Automated Capacity© loadlib and its volume (or SMS). Then, activate it (SET PROG=xx).

Dynamic definition 

Use the following command to do a dynamic definition in console mode:

SETPROG APF ADD DSN=ZCOST.ASCVnnnn.LOADLIB,VOLSER=vvvvvv A sample is provided in the APFADD member of the SAMPLIB.

4.2.2.4 Set TSO authorization for ZETALY Automated Capacity© main program

Add the ASCMAIN program into your IKJTSOxx member in segment AUTHCMD segment:

AUTHCMD NAMES(ASCMAIN) /* ZAC */

The command below allows a dynamic definition in console mode:

TSO PARMLIB UPDATE(xx)

SET IKJTSO=XX

A sample is provided in the IKJTSOXX member of the SAMPLIB.

4.2.2.5 Create catalogued procedure for the Monitor (main STC)

You can find a procedure sample in ZCASC member of the SAMPLIB.

4.2.2.5.1 Customize the main procedure PROC statement. 

//ZCASC PROC PRMGEN=xx,PRMLPA=xx,PRMALT=xx,PRMKEY=xx,PRMCTN=xx,

// DUP=N,RUNMODE=A,START=WARM,DIAG=0

Choose the parmlib member suffixes (xx) that will be used to start the STC.

• START parameter is provided with value WARM. Code START=COLD if you wish to use COLD mode when starting the STC (see chapter 4.4.1 “Starting ”). This parameter can be overridden at start time, in the start command;
• RUNMODE parameter default value is A. Code RUNMODE=M if you wish to always start in message mode or RUNMODE=R if you wish to always start in reporting only mode. This parameter can be overridden at start time, in the start command;
• DUP parameter allows several main STCs to be started on the same LPAR. The default value is N. This parameter can be overridden at start time, in the start command, for specific cases.
• DIAG parameter allows different levels of information to be obtained for diagnostic purpose. 0 indicates no diagnostic messages, 3 is the maximum and provides more information about the communication with ZAC collector process. Default value is 0. 
• PRMCTN parameter is available for container pricing feature, it's an optional parameter. This parameter member is necessary for container reporting. By default, this parameter is disable.

4.2.2.5.2 Optional: History files

If you plan to use history files, allocate them using the ALLOHIST job of the SAMPLIB and uncomment the HISTA and HISTB DD cards.

Note: this feature is provided for compatibility reasons with previous versions of ZETALY Automated Capacity©. It is strongly recommended to use SMF records instead.

4.2.2.6 Define RACF authorizations

Authorize the ZCASC userid to use Open Edition Services. If required, please contact your security administrator. Below are recommended RACF commands. You can use the RACF job of the SAMPLIB.

AG ZCASCGRP OWNER(RACFADMUSER) OMVS(GID(NNN))

AU (ZCASC) NAME('MAIN STC AUTO SOFT CAPPING') +

OWNER(RACFADMUSER) NOPASSWORD +

DFLTGRP(ZCASCGRP) OMVS(HOME(/u/asc/) UID(2221))

RDEFINE STARTED (ZCASC.*) UACC(READ) OWNER(RACFADMUSER) +

STDATA(USER(=MEMBER))

SETROPTS GENERIC(STARTED) RACLIST(STARTED) REFRESH

Code sample 1 STCs RACF authorizations 

If the RACF PROGRAM CLASS is activated on your site, you must run the job RACFWEB in the supplied SAMPLIB to define the authorized programs for the ZAC web server. 

4.2.2.7 Secure ZAC modify commands

As of version 3, ZAC checks whether modify commands issued by the current use Restoring ZAC distributed files are authorized or not. This feature is always active. ZAC will check the commands against security profiles defined in the security class you choose.

The profiles listed below may be set in generic form.

Table 2 List of ZAC commands security profiles (profiles in bold are new in V4.0) 

These rules can be defined either in RACF, CA Top-secret or CA ACF2. Use one of the following procedures.

4.2.2.7.1 Using RACF

You may use the FACILITY class to define your security profiles. However, best practices encourage using the dynamic CDT class to declare your own classes. All commands to define your RACF ZAC class and your RACF resources are provided in job RACFCMD.

Review and submit RACFCMD job of the SAMPLIB.

Using the dynamic CDT

If the dynamic CDT class is not used yet on your environment, issue the following command:

SETROPTS CLASSACT(CDT) RACLIST(CDT)

Code sample 2 CDT class activation 

Then, declare your own class as a resource class of the dynamic CDT by issuing the following RACF command:

RDEFINE CDT $ZASCCMD CDTINFO(POSIT(nnn) MAXLENGTH(44)

FIRST(ALPHA,NATIONAL) OTHER(ALPHA,NUMERIC,NATIONAL,SPECIAL)

GENERIC(ALLOWED) GENLIST(ALLOWED) RACLIST(ALLOWED))

The POSIT number should be unique and in the range 0-1023 for this class. Numbers 0-18, 57-127, 5281023 are reserved for IBM use. The class name should start with a special or national character as recommended by IBM. In the command above, the $ZASCCMD class name given is a sample and may be adapted to your needs. Then refresh the dynamic CDT:

SETROPTS RACLIST(CDT) REFRESH

It is also relevant to check that the chosen class is active, by using a SETROPTS LIST command. If it is not, use the following RACF command:

SETROPTS CLASSACT($ZASCCMD)

Then allow the class to hold generic resources and to accept generic commands:

SETROPTS GENCMD($ZASCCMD)

SETROPTS GENERIC($ZASCCMD)

We recommend that you RACLIST your class prior to append resources:

SETROPTS RACLIST($ZASCCMD)

Resource definitions

Once you have an operational class to hold your resources, you must define these resources.

Use the profile names listed previously as your resource names, either strictly or in a generic form.

RDEFINE $ZASCCMD ASC.DISPLAY.HELP UACC(NONE) OWNER(owner)

RDEFINE $ZASCCMD ASC.SET.* UACC(NONE) OWNER(owner) …

You may use the job RACFCMD job of the SAMPLIB to define your RACF resources.

User associations

Finally, define the appropriate rights your users should have on the resources. Note that ZAC only checks against a READ access on the resource.

If you plan to use ASC to send commands using the Alert process, you must authorize the Monitor STC to do this.

PERMIT ASC.DISPLAY.HELP CLASS($ZASCCMD) ACCESS(READ) ID(Stcuser)

PERMIT ASC.SET.* CLASS($ZASCCMD) ACCESS(READ) ID(Stcuser) …

If necessary, refresh the RACLIST class as the previous commands results advised you to.

SETROPTS RACLIST($ZASCCMD) REFRESH

4.2.2.7.2 Using CA-Top Secret

First, add a class to the CA-Top Secret Resource Definition Table. The following $ASCCMD class name is given as an example and should be adapted to suit your needs. The RESCODE must be set to an HEX value between 101 and 13F.

TSS ADD(RDT) RESCLASS($ZASCCMD) RESCODE(xxx) ACLST(NONE,READ) DEFACC(NONE)

Then register the resource prefix to a resource owner you want:

TSS ADD(owner) $ZASCCMD(ASC.)

Then give access to resource or resource set to specific users:

TSS PER(user1) $ZASCCMD(ASC.DISPLAY.HELP) ACCESS(READ)

TSS PER(user2) $ZASCCMD(ASC.SET.) ACCESS(READ)

You may use the job RACFCMD job of the SAMPLIB designed for RACF and adapt it to define your resources.

4.2.2.7.3 Using CA ACF2

ACF2 requires a mapping to ensure compatibility between SAF classes and its own 3-character resource types. In the following excerpt of code $ZASCCMD and ASC are given as samples and should be adapted to suit your needs. Mapping is done by inserting a CLASMAP record as follows:

CLASMAP RESOURCE($ZASCCMD) RSRCTYPE(ASC) ENTITYLN(44)

Then define the access rules according to the profile table given earlier. Note in the following sample that the TYPE has necessarily the same value as the RSRCTYPE above. Here we want user1 and user2 to have access to resource ASC.HELP and ASC.SET respectively. ASC application needs to have a READ access.

$KEY(ASC) TYPE(ASC)

HELP UID(user1) SERVICE(READ) ALLOW SET UID(user2) SERVICE(READ) ALLOW

You may use the job RACFCMD job of the SAMPLIB designed for RACF and adapt it to define your resources.

4.2.2.8 Operations on ZFS

ZAC uses 3 ZFS files to store reports elements.

• The main ZFS file contains ZAC programs and elements requested to navigate in reports. It is provided.
• The Web ZFS file, contains current web reports. It is not provided; you must create it.
• The Backup ZFS file, contains archived reports. It is not provided; you must create it.

4.2.2.8.1 Creation of ZETALY Automated Capacity© ZFS Directories

Review and submit the ZFSMKDIR job of the SAMPLIB.

4.2.2.8.2 ZAC ZFS files mount

Mount the ZAC ZFS main files in the directory created in the previous step.

Review and submit the ZFSMOUNT job of the SAMPLIB.

You may verify that the files are correctly mounted by using the ‘D OMVS,F’ command.

4.2.2.8.3 Populate ZFS Web file

Four pre-defined files are necessary to ZAC reports viewing.

• Doc.htm The online messages and codes manual.
• Index.htm The html definition of the business view;
• Prmasc.htm The Html page which format the parameters web view;
• Stclog.htm The Html page which format the web representation of the STC job log; These files are delivered in binary format and are stored in the HTM library. You must copy these files to the allocated Web ZFS dataset.

Review and submit HTMMPUT job of the SAMPLIB.

4.2.2.8.4 Files owner update

To be accessed by the ZAC components, the defined Omvs files must have correct owners. Review and submit ZFSCHOWN job of the SAMPLIB.

4.2.2.8.5 Make ZAC file mounts permanent

Add the ZAC ZFS mount commands into the active BPXPRMxx member of your z/OS PARMLIB, to ensure that ZFS files remain mounted after an IPL. You can use the SAMPLIB member BPXPRMXX.

Customize HLQ1 to match your naming conventions and add the following entries.

If you changed the default path, customize the MOUNTPOINT too.

MOUNT FILESYSTEM(‘HLQ1.ASCVnnnn.ZFS’)

TYPE(ZFS) (or HFS)

MODE(RDWR)

MOUNTPOINT(‘/u/asc/’)

MOUNT FILESYSTEM(‘HLQ1.ASCVnnnn.WEB.ZFS’)

TYPE(ZFS)

MODE(RDWR)

MOUNTPOINT(‘/u/ascweb/’)

Code sample 3 Make ASC ZFS mount points permanent 

4.2.2.8.6 Optional: Create a zcost.resolve file. 

If you are using HMC setting method, during the LPAR DEFCAP setting, ZETALY Automated Capacity© runs UNIX SERVICES processes. Usually, UNIX SERVICES processes perform TCP/IP prefix resolution using /etc/resolv.conf OMVS file that contains TCPDATA parameters.

However, some sites do not allow the use of this file. In this case, define a file named zcost.resolve under your ZETALY Automated Capacity© /pgm path and copy the TCPDATA content to it. This file will be used during the LPAR DEFCAP setting process, instead of the standard /etc/resolv.conf file.

4.2.2.9 Update the Key in the ASCKEYxx member of ASC parmlib

You must update the key in the ASCKEYxx member in the PARMLIB, with the software key provided by your product vendor.

Note: An ASC0951W warning message will be sent to the ZAC STC log and a SYSLOG, 30 days before the ZAC key expires. This message is sent every day at 12:00 and at each start of the main STC. Once the available period is expired, the product continues to run until it is stopped. The ASC0951W message is still sent but the text is changed to alert that the key has expired. It can also be dynamically refreshed by console command F ZCASCSTC,REFRESHKEY

Table 3 ZAC KEY file example 

****** ************************ Top of Data ***************************

000001 * CPU KEY OBTAINED FROM ZETALY

000002 2KYGX-65DBZ-F5UV3-TJ75J CPC 0B62B EXPIRATION 20190131

****** *********************** Bottom of Data *************************

4.2.3 Installing ZETALY Automated Capacity© Reporting web server

The ZAC web reporting application can run either on DOMINO web server or APACHE web server. You must choose which one you plan to use. Your possible choices depend on the z/OS version you are running.

• If you are using a z/OS release prior z/OS V2.1 you must use DOMINO web server.
• if you are using z/OS V2.2 or above you must use Apache web server.
• Because with z/OS V2.1 APACHE web server is provided through "IBM ported tools", if you are using z/OS V2.1 you can choose either APACHE or DOMINO web server.

Refer to the appropriate installation process below.

4.2.3.1 Using DOMINO as web server

All installation jobs are in the customized SAMPLIB library.

4.2.3.1.1 Create Catalogued Procedure for the Web Reporter in a system PROCLIB

- e.g.: SYS1.PROCLIB(ZCASCW)

You can find a procedure sample in ZCASCW member of the SAMPLIB.

4.2.3.1.2 Customize the web reporter procedure. 

//ZCASCW PROC ZCASCPRM='-R /u/asc/zcost.conf -P 2312’

Warning: Check the PORT in the ZCASCW procedure. Check the path in “zcost.conf” and

“zcost.envvars” files.

4.2.3.1.3 Define RACF Authorizations

Authorize the ZCASCW userid to use Open Edition Services. If required, please contact your security administrator. Below are recommended RACF commands. You can use the RACFW job of the SAMPLIB.

Table 4 RACF authorizations definition for ZAC Web Reporter 

AU (ZCASCW) NAME('WEB REPORT STC AUTO SOFT CAPPING') +

OWNER(RACFADMUSER) NOPASSWORD +

DFLTGRP(ZCASCGRP) OMVS(UID(2222))

PERMIT BPX.SERVER CLASS(FACILITY) ID(ZCASCW) ACCESS(UPDATE)

RDEFINE STARTED (ZCASCW.*) UACC(READ) OWNER(RACFADMUSER) +

STDATA(USER(=MEMBER))

SETROPTS GENERIC(STARTED) RACLIST(STARTED) REFRESH

SETROPTS GENERIC(FACILITY) RACLIST(FACILITY) REFRESH

If the RACF PROGRAM CLASS is activated on your site, run the job RACFWEB to define the authorized programs for the ZAC web server.

4.2.3.1.4 Create the www .browsable file

The www.browsable file is an empty file used by DOMINO HTTP server to obtain read authorization on the directory where archived reports are stored (DOMINO HTTP server only). Review and submit the job ZFSBKWWW job of the SAMPLIB.

4.2.3.1.5 Create the DOMINO zcost.conf file. 

This file contains the directives required for the web server on which ZAC reporting application will run.

First, check ZFS ZAC program file is mounted.

Review and submit the JOB ZCOSTCNF job of the SAMPLIB.

4.2.3.2 Using APACHE as web server.

This installation process assumes an APACHE Server is already installed on your z/OS environment. The ZAC reporting web server will be regarded as a virtual web server and then declared as a "VirtualHost" in your APACHE instance.

All installation jobs are in the customized SAMPLIB library.

4.2.3.2.1 Create the APACHE zcost.conf file. 

This file contains the directives required for the web server on which ZAC reporting application will run.

First, check ZFS ZAC program file is mounted.

Review and submit the job APCHCONF job of the SAMPLIB.

4.2.3.2.2 Declare ZAC zcost.conf file in your existing APACHE configuration file. 

To locate your APACHE configuration file, look at your APACHE Stc Jcl (HTTPDACS) and get DIR and CONF parameters values. Here is an example of APACHE procedure:

//HTTPDACS PROC ACTION='start'

// DIR='/ihsconfig/his/httpdacs',

// CONF='conf/httpd.conf' 

//HIS EXEC PGM=BPXBATCH,

// PARM='SH &DIR/bin/apachectl -k &ACTION -f &CONF -DNO_DETACH',

// MEMLIMIT=512M

In this example, the APACHE configuration file is /ishconfig/ish/httpdacs/conf/httpd.conf

The directive you must add is: Include "/asc_path_name/zcost.conf"

To assist you, this directive has been generated in the SYSTSPRT file during zcost.file creation by the job

APCHCONF.

Edit your APACHE configuration file and add the directive at the end of it, as the sample below:

EDIT /ihsconfig/ihs/httpdacs/conf/httpd.conf Line 0000000895 Col 001 080

Command ===> Scroll ===> CSR

# The following example configuration can be activated by uncommenting # the LoadModule directive.

#LoadModule net_trace_module modules/debug/mod_net_trace.so

NetTraceFile /tmp/nettrace

NetTrace client * dest file event senddata=65535 event recvdata=65535

Include "/u/asc/zcost.conf" 

******************************** Bottom of Data *************************

Validate APACHE configuration file by the following commands from OMVS (use TSO OMVS command):

ZCUSR2:/u: >cd /ihsconfig/ihs/httpdacs/bin

ZCUSR2:/ihsconfig/ihs/httpdacs/bin: >apachectl configtest Syntax OK ZCUSR2:/ihsconfig/ihs/httpdacs/bin: >

4.2.3.2.3 Enable Reporting SAF sign on. 

By default, the connection to ZAC web reporting requires a SAF sign on.

In the APACHE configuration file verify that following modules are declared and uncommented (To uncomment a line, remove the hashtag in first column).

LoadModule auth_basic_module modules/mod_auth_basic.so

LoadModule authz_user_module modules/mod_authz_user.so

LoadModule authnz_saf_module modules/mod_authnz_saf.so

LoadModule authz_default_module modules/mod_authz_default.so

V8.5 only: LoadModule authz_default_module modules/mod_authz_default.so 

V9.0 only: LoadModule authz_core_module modules/mod_authz_core.so

If some module declarations are missing, add the declarations as above and verify in the APACHE modules directory that the modules are present. Based on the previous sample PROC, the path should be:

/ihsconfig/ihs/httpdacs/modules/

4.2.3.2.4 Optional: Disabled SAF sign on

This step is only required if you are using APACHE web server and you want to disable the sign on to access the ZAC web reporting.

Edit the zcost.conf configuration file, then remove the following lines :

AuthName "ZAC web reporting"

AuthType Basic

AuthBasicProvider saf

Require valid-user

AuthSAFExpiration "EXPIRED! oldpw/newpw/newpw"

AuthSAFReEnter "Enter new password one more time"

4.2.3.2.5 Optional: enable HyperText Transfer Protocol Secure (https)

This step is only required if you plan to enable https protocol over TLS.

You can use your own existing root certificate signed by a certification authority (CA) as GlobalSign or others. In that case, you can directly jump to chapter 4.2.3.2.5.4 The process below applies only to RACF security server..

4.2.3.2.5.1 Define zCost certificate authority (root certificate)

This certificate (AUTH) will be used to sign the web reporting certificate (SITE). It's a root authority certificate

By default, all required parameters for RACDCERT utility are provided. You can update them if desired. If you modify one of them, ensure in next steps that all parameters are coherent. Review and submit job APCHSSL1.

4.2.3.2.5.2 Optional: Export root certificate

The certificate authority public key can be exported in order to be imported in your browser to prevent security warning during web reporting connections. This feature applies only if the web reporting URL is managed thru a DNS. If you use an IP address a security warning will always be emitted.

• Review and submit APCHSSL2

The public key is stored in your HLQ.AUTHORTY.CERT dataset.

• Download this dataset on your computer (using ftp in ASCII mode) with name zcost.crt.
• Depending on the browser you are using, import the zcost.crt certificate. Follow the appropriate process below:

Internet explorer 

Double click on zcost.crt file, then accept importation (this process will update Windows registry). You could need administrator privileges.

Firefox 

From Firefox menu:

Tools -> advanced -> Certificates -> display certificates.

Ensure that tabs "Authority" is selected. Click on import button then select zcost.crt file. Accept all confirmations.

Chrome 

From Options:

Parameters -> Display advanced parameters -> managed certificates.

Select "Trusted Root Certification Authorities" tabs. Click on import button then select zcost.crt file. Accept all confirmations.

4.2.3.2.5.3 Create SITE certificate

If you are using a DNS, change DOMAIN name and URL as required. All other parameters can be stay as they are delivered except if you have updated them in first step. Review and submit APCHSSL3

4.2.3.2.5.4 Create and connect KEYRING with SITE certificate

Review and submit APCHSSL4

4.2.3.2.5.5 Set RACF FACILITY access

Review and submit APCHSSL5 

4.2.3.2.5.6 Create Apache configuration file for https support

Review and submit APCHSSL6 (ensure that the KEYRING name is correct)

4.2.3.2.6 Define BPX RACF Authorizations. 

Authorize the HTTPDACS userid assigned to Apache HTTPDACS Stc to use BPX.SERVER resource. If required, please contact your security administrator. Below are recommended RACF commands. You can use the RACFWA job of the SAMPLIB.

Table 5 RACF authorizations definition to permit APACHE Stc to use BPX.SERVER resource. 

PERMIT BPX.SERVER CLASS(FACILITY) +

ID(HTTPDACS) +

ACCESS(UPDATE)

SETROPTS GENERIC(FACILITY) RACLIST(FACILITY) REFRESH

4.2.4 Installing ZETALY Automated Capacity© Collector

You must install one collector instance on each LPAR, which will be managed by the monitor. 

4.2.4.1 Define the RESTART Dataset

ZETALY Automated Capacity© Collector is designed to allow for restarting in “WARM mode”. This feature requires storing the “restart” data into a file used at restart time. Review and submit ALLORDSC job of the SAMPLIB.

4.2.4.2 Create the STC procedure in a system PROCLIB

- e.g.: SYS1.PROCLIB(ZCASCCOL)

You can find a procedure sample in the ZCASCCOL member of the SAMPLIB.

//ZCASCCOL PROC INTERVAL=120,PORT=2391,

// SECCLASS=$ZASCCMD,DUP=N,DIAG=0,START=WARM,PRMKEY=00

• INTERVAL parameter represents the interval (in seconds) between two collects. The collector will aggregate metrics along the interval and produces a set of measures at its end. The value must be chosen accordingly (same value) to INTERVAL general parameter. For more information, refer to ZETALY Automated Capacity© User's Guide.
• PORT is the IP port that will be used by the monitor to communicate with the collector. This is a port on which the collector is listen to. The value must be chosen accordingly to COLLIPPORT LPAR parameter. For more information, refer to ZETALY Automated Capacity© User's Guide.
• DUP parameter allows several Collectors to be started on the same LPAR. The default value is N. The purpose of this parameter is to be overridden at start time, in the start command, for specific cases.
• SECCLASS parameter is the security class you have chosen to define security profiles used to control collector commands. The value must be chosen accordingly to SECCLASS general parameter. You may use a specific class or use the existing FACILITY class. For more information, refer to ZETALY Automated Capacity© User's Guide.
• DIAG is the diagnostic level. The value can be 0 to 3, where 0 is “no diag” and 3 is the most detailed level. Diagnostic data is written into SYSPRINT dataset. 0 is the default.
• START parameter is provided with value WARM. In normal operation, the collector may always start in WARM mode. Code START=COLD if you exceptionally would use COLD mode when starting the STC (see chapter 4.6.1 “Starting the ZAC collector”). This parameter can be overridden at start time, in the start command;
• PRMKEY is the suffix used to build the name of the parmlib member, which contains the product key.

4.2.4.2.1 Define RACF Authorizations

Below are recommended RACF commands. You may use the RACFCOL job of the SAMPLIB.

AG ZCASCGRP OWNER(RACFADMUSER) OMVS(GID(NNN))

AU (ZCASCCOL)NAME('ASC COLLECTOR') +

OWNER(RACFADMUSER) NOPASSWORD +

DFLTGRP(ZCASCGRP))

RDEFINE STARTED (ZCASCCOL.*) UACC(READ) OWNER(RACFADMUSER) +

STDATA(USER(=MEMBER))

SETROPTS GENERIC(STARTED) RACLIST(STARTED) REFRESH

Code sample 4 RACF authorizations definition for ZAC Collector 

4.2.4.2.2 Secure ZAC Collector Modify Commands

As of version 3, ZAC checks whether modify commands issued by the current user are authorized or not. ZAC will check the commands against security profiles defined in the security class you chose. The profiles listed below may be set in generic form.

You may use the RACFCMDC job of the SAMPLIB.

If you do not plan to create a new security class, you may set the SECCLASS general parameter to the FACILITY value.

4.3 Migrating ZETALY Automated Capacity©

4.3.1 Dismount Backup ZFS file

If you want to reuse your archived reports with the new version of ZAC you may unmount it from the previous one and remount it into the new one.

4.3.2 Migrate ZAC parmlib members

4.3.2.1 Migrate ASCGENxx ZAC parmlib members

Two parameters have been added in V4.4.00. You may add them in yours V4.2 ASCGENxx members, if you plan to change the defaults (see ZETALY Automated Capacity© user guide for more information).

• BCPII_MAXTASKS Bcpii maximum parallel tasks. Default is 5.
• BCPII_TIMEOUT Bcpii set task timeout. Default is 60 seconds

4.3.2.2 Migrate ASCLPAxx ZAC parmlib members

V4.2, V4.3 and V4.4 members are compatible. No action required.

4.3.2.3 Migrate ASCALTxx ZAC parmlib members

A lot of new variable have been added in Alert process in V4.3 and V4.4. V4.2 members are compatible, but you may review new available variables (from ASCALT00 V4.4 provided sample) to code new alerts about new consumption metrics and new container rules.

4.3.2.4 Create a new ASCCTNxx parmlib member

If you plan to manage containers, you must define a new ASCCTNxx member in your parmlib. Refer to the provided ASCCTN00 member sample to define your containers.

4.3.3 Define new ZAC commands authorization profiles

ZETALY Automated Capacity© commands are checked against security profiles. Therefore, you must add new security profiles to be able to use new V4.4 ZAC commands. The new commands are:

4.3.3.1 New commands appeared in V4.1

4.3.3.2 New commands appeared in V4.2

• SET MOBILE (ASC.SET.MOBILE)

4.3.3.3 New commands appeared in V4.3 and V4.4

4.4 Starting / Stopping ZETALY Automated Capacity©

4.4.1 Starting the Monitor

Use the following MVS command: S ZCASC

or

S ZCASC,START=COLD

or

S ZCASC,START=WARM

By default, (without overriding the start mode in the start command), ZETALY Automated Capacity© starts in the (COLD/WARM) mode defined in the JCL procedure. However, when starting for the first time the mode is always COLD (because the RDS file is empty).

Cold start: The context is initialized. All general and LPAR parameters are loaded from the selected parmlib members. Status of LPARs, last settings done, last activated periods and alerts status are re-initialized. Warm start: The context is restored. General and LPAR parameters are reloaded from the restart dataset. Status of LPARs, last settings done, last activated periods and alerts status are loaded from the restart dataset.

Messages issued:

Figure 3 Examples of start messages in the system log 

ZAC is ready to work from the ASC0050I message on.

Any SYSIN or DEFAULT parameters may be overridden with PRMxxx= - e.g.:

S ZCASC,PRMGEN=nn,PRMLPA=nn,PRMCTN=nn,PRMALT=nn,PRMKEY=nn Or using a start command parameter

S ZCASC,RUNMODE=Message

Note: ZETALY Automated Capacity© is protected against duplicate occurrences. By default, to avoid production mistakes, you cannot simultaneously start two ZETALY Automated Capacity© monitor STCs on the same partition. However, in some cases (for example during the migration process), you may have to start two ZETALY Automated Capacity© monitor STCs. Use the DUP parameter to allow duplicate monitors.

S ZCASC,DUP=YES

4.4.2 Stopping the Monitor

Use the following MVS command:

P ZCASC 

Messages issued:

ASC0999I ZETALY AUTOMATED CAPACITY MAIN TASK STOPPED

4.5 Starting /Stopping Web Reporter

4.5.1 Starting the Reporter using a Domino web server

Use the following MVS command:

S ZCASCW

Messages issued:

IMW3534I PID: 67174526 SERVER STARTING

IMW3536I SA 67174526 0.0.0.0:2312 * * READY

Note: the STC main program is IMWHTTPD. This program is supplied by IBM. Verify that the IMWHTTPD program is present in your LINKLIB (SYS1.LINKLIB).

4.5.2 Starting the Reporter using an APACHE web server

If the APACHE web server which support the ZAC Reporting is not active, you must start it. Use the following MVS command:

S HTTPDACS

Messages issued:

$HASP373 HTTPDACS STARTED (HTTPDACS) IHS is active.

4.5.3 Verifying that web reporting is operational

ZETALY Automated Capacity report is a web application. To access it, you must use a browser. The supported browsers are:

• Microsoft Internet Explorer Version 11+
• Mozilla Firefox version 42+
• Google chrome version 30+

Connect your web browser to the HTTP server on which ZAC is installed.

Select http://xxx.xxx.xxx.xxx:pppp in your web browser.

You can pick up the IP address xxx.xxx.xxx.xxx from the LPAR on which the Web server runs, by using the command:

TSO NETSTAT HOME.

The port number pppp is the one you defined when customizing the installation parameters.

E.g.: http://10.44.22.23:2412

You will get the ZETALY Automated Capacity© home page.

4.5.4 Stopping the Reporter using a Domino web server

Use the following MVS command:

P ZCASCW

Messages issued:

BPXM023I (WASCZ301) IMW3540I SA 83951689 0.0.0.0:2301 * * STOPPING WORK

BPXM023I (WASCZ301) IMW3541I SA 83951689 0.0.0.0:2301 * * TERMINATING NOW

Figure 4 ZAC Reporter stopping messages 

4.5.5 Stopping the Reporter using the APACHE web server

Use the following MVS command:

P HTTPDACS

If your Apache STC name has less than 8 characters a message is displayed in the SYSLOG at start time, to provide the name to use for modifying and stop command.

Ex.

0.0.0.0:2401. Use jobname HTTPD16 for console commands.

P HTTPD16 Messages issued:

BPXM023I (HTTPDACS) IHS is stopping

$HASP395 HTTPDACS ENDED - RC=0000

4.6 Starting /Stopping ZAC Collector

4.6.1 Starting the ZAC Collector

From the V4.4.00 version, the collector retrieves LPARs MSU consumptions and stack them over the current billing month. The stacked consumptions are stored in the new collector Restart dataset. In order to preserve the monthly consumptions, the collector should always restart in "WARM" mode. However, to be able to reset the monthly cumulated consumptions in special cases, a "COLD" start is possible. In this case, all monthly consumptions will be reset to 0.

Use the following MVS command: S ZCASCCOL

or

S ZCASCCOL,START=WARM

or

S ZCASCCOL,START=COLD

By default, (without overriding the start mode in the start command), the collector starts in the

(COLD/WARM) mode defined in the JCL procedure. However, when starting for the first time (installation time) the mode is always COLD (because the Collector RDS file is empty).

COLD start: The monthly accumulated consumptions are initialized.

WARM start: The context is restored. All monthly accumulated consumptions are restored from the Restart Dataset.

Messages issued:

S ZCASCCOL

Messages issued:

Figure 5 Example of start messages in the system log 

4.6.2 Stopping the ZAC Collector

Use the following MVS command:

P ZCASCCOL

Messages issued:

ASC1306I STOP COMMAND RECEIVED

ASC1902I IP SERVER NOW STOPPED

ASC1999I ZETALY AUTOMATED CAPACITY COLLECTOR STOPPED

Figure 6 ZAC Collector stopping messages 

4.7 Testing ZAC collector

You can use the TSTCOL job of the SAMPLIB to test the communication and response times between the ZCASC and ASC collector's agents.

The output indicates if the communication is correct or not. You must populate the SYSIN with the LPARs you want to collect.

There are two outputs for this job:

• The first one is written into a file with DDNAME RESULT. It contains the collected metrics for all the objects defined into the SYSIN dataset
• The second one is written into a file with DDNAME SYSOUT. It contains the report of the collect, including return codes and response times of the TCP/IP requests performed

*LPARNAME CPCNAME LPAR_IP_ADR COLLECTOR_IP_PORT

LPAR1 AC64B 10.22.42.30 2391

Code sample 5 Example of SYSIN 

*ColN Collect_Time CpcName CpcID Type Mdl Capty Cp Lpar Sysname .... 00001 20141015152400 AC64B 2097 704 0531 04 LPAR1 PROD01

*Srv_Cls Pe Workload Im Imsu

BATMDM 01 BATCH 03 0000.00

STCLOM 01 STARTED 06 0242.57

STCMDM 01 STARTED 03 0000.00

TSO01 01 TSOOTHER 01 0000.00

TSO01 02 TSOOTHER 02 0000.00

SYSTEM 01 SYSTEM 00 0036.61

SYSSTC 01 SYSTEM 00 0078.71 SYSOTHER 01 SYSTEM 00 0000.00

Figure 7 Example of RESULT 

ZETALY AUTOMATED CAPACITY COLLECTOR TEST PROGRAM

STATUS OF COLLECTS

20141015152422 Collect LPAR1 10.22.42.30 :2391 RC=00000000 resp=235.61 ms

COLLECT 0000001 20141015152422-> 20141015152400 RC=0 DIAG_FLAGS=00 00 00 00 00

DIAG_CODES=00000000 00000000 00000000

Figure 8 Example of SYSOUT 

5 Messages and codes

5.1 Messages and codes table

5.1.1 ASCxxxxx messages

Messages ASCnnnnx are explained in a separate documentation. Refer to ZAC “Messages and codes reference” documentation ZAC-MCR-4300-nn-E for more information.

5.1.2 HMCxxxxx messages

Messages HMCnnnnx are explained in a separate documentation. Refer to ZAC “Messages and codes reference” documentation ZAC-MCR-4100-nn-E for more information.

6 Enabling communication with BCPii

6.1 ZETALY Automated Capacity© architecture sample using BCPii

Figure 9 ZAC architecture with BCPii 

6.2 Enable BCPii communication on the SE

SETMETHOD=BCPii is required in ZETALY Automated Capacity© PARMLIB.

To enable communication with the SE you must enable the “cross partition authority” on the HMC. Perform the following steps on the HMC:

1. Select the CPC that is required;
2. Open Single Object Operations;
3. Open the CPC Operational Customization task list;
4. Highlight the CPC icon;
5. Open the Change LPAR Security task, and the Change Logical Partition Security window displays;
6. Check the “Cross Partition Authority” checkbox;

Figure 10 Cross partition authority setting on HMC 

1. Select Save and Change.

Make the same updates to all the CPCs you want BCPii to communicate with and not just the CPC on which the BCPii application will execute. 

6.3 Define BCPii community name on the SE

Perform the following steps on the HMC:

• Select the CPC that is required.
• Open Single Object Operations.
• Select the Console Actions view.
• Select Support Element Settings.
• Open Customize API Settings.

Figure 11 Customize API HMC window 

• Check the Enable SNMP API checkbox.
• Make sure that the SNMP agent parameters are blank.
• Add a BCPii community name. Click on Add. When a window is prompted, fill in the following fields:
• Name: BCPii community (uppercase only 1-16 alphanumeric character).
• Address: Must be 127.0.0.1 (do not change).
• Network mask: Must be 255.255.255.255 (do not change).
• Access type: Read/Write.
• Save the changes.

Do the same updates to all the CPCs you want BCPii to communicate with. 

Figure 12 Customize API settings sample 

Repeat all previous steps on all the other SE associated with the CPCs with which you want to access BCPii. 

6.4 Set BCPii permissions in HMC as of Z14

Starting from Z14, after an installation or machine upgrade, new BCPii access permission setting options are available on the HMC.

The factory default value of this option is set to ‘Disabled’ for each z14 LPAR.

Existing applications that use the BCPii transport cannot run on a z14 LPAR with this default setting. 

For these applications, BCPii access must be re-enabled on the z14 LPAR by changing the default value to ‘Send’ or ‘Receive’ or ‘Send & Receive’, depending on whether the LPAR is BCPii request origin, target, or both.

The new facility is part of the HMC LPAR Security Settings task. It allows to change BCPii permissions at runtime, in the image activation profile, or both.

Figure 13 Sample HCM panel showing BCPii permission settings 

6.5 Define BCPII general SAF authority

A sample JCL (RACFBCPI) is provided in the ZAC sample library to define SAF resource. Customize the JCL with your parameters:

• BCPii community name (uppercase only);
• Your NetID;
• The ZAC STC user ID.

Submit this JCL for each CPC on which the LPARs managed by ZAC are installed.

RDEFINE FACILITY HWI.APPLNAME.HWISERV +

UACC(NONE)

PERMIT HWI.APPLNAME.HWISERV + CLASS(FACILITY) +

ID(ASCSTC) +

ACCESS(READ)

RDEFINE FACILITY HWI.TARGET.NETID.* +

UACC(NONE)

PERMIT HWI.TARGET.NETID.* +

CLASS(FACILITY) +

ID(ASCSTC) +

ACCESS(ALTER)

RALTER FACILITY HWI.TARGET.NETID.* APPLDATA('COMMUNITY') SETROPTS RACLIST(FACILITY) REFRESH

Code sample 6 RACF definition sample 

6.6 Startup and shutdown BCPii

The BCPii address space normally does not need to be started or shut down. BCPii initialization occurs during system IPL.

Start Command: 

S HWISTART Stop Command: 

P HWIBCPII

6.7 Testing the BCPii communication

(This step is only required for SETMETHOD=BPCII.)

You can test the communication between the LPAR on which ZETALY Automated Capacity© runs and the HMC/SE. The test program will attempt to modify Define Capacity and/or the weight of LPAR. You must supply a correct Netid in PARM= on the EXEC card and set values in the SYSIN dataset.

This job requires a valid product authorization key. This key is the same as the product key delivered by ZETALY® and must be set in the KEYS dataset.

The output indicates if the modification(s) were successful. If they were, a Define Capacity and/or the Weight are modified. You may verify the success on the HMC. If the communication did not work, an explanation of the trouble is written into the SYSOUT dataset. The SYSOUT dataset will contain BCPii error messages and if available, additional standard BCPii diagnostic fields.

In case of failure of the job, refer to “MVS Programming: Callable Services for High-Level Languages” Part 6 (BCPii) for more information.

For more information about BCPii: 

http://www.redbooks.ibm.com/redbooks/pdfs/sg247804.pdf

http://publib.boulder.ibm.com/infocenter/zos/v1r11/index.jsp?topic=/com.ibm.zos.r11.ieac100/strshu.ht m

7 Enabling communication with the HMC

7.1 ZETALY Automated Capacity© architecture sample with the HMC API

7.2 Configuring the firewall (optional)

If you plan to use the BCPII feature instead of the HMC API, skip to Chapter 6: “Enabling communication with BCPii”.

(This step is only required for SETMETHOD=HMC.)

ZETALY Automated Capacity© can communicate with the HMC using SNMP and the HMC API.

The standard port used to communicate using SNMP is port 161 with UDP protocol. The standard port used to communicate with the HMC API is port 3161 with TCP protocol. If you use a firewall, open the following connections in your firewall:

Port 161 UDP for HMC @IP with dynamic port for the z/OS hosting ZETALY Automated Capacity© @IP

Port 3161 TCP for HMC @IP with dynamic port for the z/OS hosting ZETALY Automated Capacity© @IP

7.3 Configuring the HMC API (SETMETHOD=HMC)

(This step is only required for SETMETHOD=HMC.)

For complete information look at Resource Link Documentation:

https://www-01.ibm.com/servers/resourcelink

The Console’s API configuration steps can be performed by using the Customize API Settings task of the Hardware Management Console Settings or Support Element Settings task group. This task group is found under Console Actions in the Views area. To configure the Console for API support:

• Log on to the Console in Access Administrator mode;
• Open the Hardware Management Console Settings or the Support Element Settings task group;
• Start the Customize API Settings task;
• Tick the Enable SNMP checkbox, add a Community Name, and associated parameters;
• Then you need to restart the Console to apply the changes.

7.3.1 Detailed procedure to configure the console for API support

1. Log on to the Console in Access Administrator mode. User ACSADMIN. Select the Console Actions icon and double click it.

Figure 15 HMC Console Action 

1. Open the Hardware Management Console Settings or the Support Element Settings (task group). Select the Hardware Management Console Settings icon and double click it.

Figure 16 Hardware Management Console Settings 

1. Start the Customize API Settings task.

Select the Customize API Settings icon and double click it.

Figure 17 Customize API Settings 

1. Tick the Enable SNMP checkbox and add a Community Name Select the Add icon and click it.

Figure 18 Add Community name 

Enter a “Community Name” (e.g. ZCOST).

This field should be filled in with any character string. Each community name in the list must be unique. Please note that this field is case sensitive. Note the community name(s) that are to be used by applications using the Console’s APIs, since they will need to be specified on the HwmcaInitialize calls issued by those applications.

Enter Address : 0.0.0.0

Network mask / Prefix : 0.0.0.0

Access Type: Use this field to specify the type of access that is allowed for the community. The access type for the community(ies) that are to be used by applications using the Console’s APIs MUST be read/write.

Select Read/write. Click on OK.

Figure 19 Set Community Name information 

Click on APPLY.

Figure 20 Validate API Settings customization 

Figure 21 SNMP Configuration message 

Click on OK.

Figure 22 Settings before HMC restart 

Now you must restart the HMC to apply all the changes. 

7.4 Testing the HMC API and communication

(This step is only required for SETMETHOD=HMC.)

You can use the TSTHMC job supplied in ZETALY Automated Capacity© SAMPLIB to test all network paths and APIs between the LPAR on which ZETALY Automated Capacity© runs and the HMC/SE. The output indicates if the communication is correct or not.

If it is correct, a list of LPARs which can be reached by ZETALY Automated Capacity© is generated. If the communication is not correct, an explanation of the problem is displayed.

Warning: when ZETALY Automated Capacity© encounters a problem with an HMC, it tries to switch to the second HMC. In this case, it is necessary that the LPAR involved in the failure can be reached through the second HMC. To avoid problems, you may verify using the test job that all the LPARs are reachable through both HMCs.

7.5 HMC communication troubleshooting

You must consider that some interfaces like WEB & login conflict with the HMC API access mode. Some of these interfaces are listed below:

• CHANGE LPAR DEFINITION on HMC or via the web interface;
• SOO mode from HMC to control the CPC; • SERVICE MODE login on SE;
• Maintenance on HMC or SE.

To avoid problems due to HMC conflicts, you can temporarily disable ZETALY Automated Capacity© HMC actions during a planned intervention on the HMC or the SE. Use the command below:

F ZCASC,RUNMODE=MESSAGE

F ZCASC,RUNMODE=ACTIVE allows you to reactivate ZETALY Automated Capacity© actions after the planned intervention is finished.

7.6 Behavior of ZETALY Automated Capacity© during a communication problem with the HMC

When a communication problem occurs, the behavior of ZETALY Automated Capacity© is the following:

Interval 1

SET LPAR1 via HMC1 --> error --> switch to HMC2 and retry setting LPAR1 via HMC2 --> error --> stop settings for interval -→ Error message (ASC0710W)

Interval 2

SET LPAR1 via HMC2 --> error --> switch to HMC1 and retry setting LPAR1 via HMC1 --> error --> stop settings for interval -→ Error message (ASC0710W)

Interval 3

SET LPAR1 via HMC1 --> error --> switch to HMC2 and retry setting LPAR1 via HMC2 --> error --> stop

ZCASC with the error -→ message (ASC0805E)

Note: Typically, this behavior occurs when the HMC interface is used by another user during an ZAC setting request. (see chapter 7.5 “HMC communication troubleshooting”).

8 Managing LPARs with ZETALY Automated Capacity©

8.1 Warning about HMC use

ZETALY Automated Capacity© applies a constant control on your Defined Capacity sum (CPCMAX, CMPMAX general parameter) and works within this sum.

If you directly use the HMC to change Defined Capacities for some LPARs, you must ensure consistency with the CPCMAX or CMPMAX parameters.

In fact, if your HMC change makes the sum of the DCs exceed the value of CPCMAX or CMPMAX, then ZETALY Automated Capacity© will adjust the sum of the DCs to the Maximum limit. In this case it is possible that ZETALY Automated Capacity© forces to steal MSUs from an important LPAR and thus affect its behavior.

In this case, an ASC0706W warning message is sent.

If your HMC static change makes the sum of the DCs become lower than the value of CPCMIN or CMPMIN, then processing continues and the ASC0707W warning message is sent.

8.2 IPL & LOAD method

The Defined Capacity (DC) and Weight parameters set by ZETALY Automated Capacity© are stored in the current image profile located in HSA: it is a “warm” setting.

It is better to remain consistent with ZETALY Automated Capacity© CPCMAX or CMPMAX value. Then to make an IPL, you may perform a single LOAD because the LOAD action uses the current LPAR definition loaded into HSA memory.

On the other hand, an ACTIVATE reloads for this LPAR the Image Profile definitions such as DC, Weight, NB CP, memory, Clock, etc., which are stored into the HMC (cold setting).

For example, if the current LPAR DC from HSA memory is lower than the Image Profile DC and if you request an ACTIVATE for this LPAR, the value of CPCMAX or CMPMAX will be exceeded. ZETALY Automated Capacity© will adjust the sum of the DCs to the value of CPCMAX or CMPMAX at the next interval, but you must be careful as explained in chapter 8.1 “Warning about HMC use”, above. We recommended paying attention to this fact when you manage your images on the CPC. 

End of this Document