By Katherine Livecchi, z/OS BCPii System Tester
In z/OS System Test, we test with many different hardware configurations. The configurations are defined in image activation profiles, which are customized using the Hardware Management Console (HMC) or Support Element (SE). When BCPii added support in z/OS V1R11 to update attributes in image activation profiles from a z/OS application, I began to think about using BCPii to help automate some system test setup.
I created my first BCPii app four years ago using an internal z/OS test tool. Because BCPii is installed on a number of CPCs on our test floor, my app can run from any image where BCPii is active and can target image activation profiles on multiple CPCs. Once the image activation profiles are updated and verified, the images themselves are reactivated - using the activation profiles - and IPL'd.
My BCPii app quickly became popular with other system testers who also use it to set up their test environments. What a convenient way to customize image activation profiles prior to testing! Each tester stores their test configurations in separate input files and runs the app with one of their files as input. It's so much easier than the tedious process of updating the image activation profiles manually with the HMC or SE.
When the BCPii REXX interface became available in z/OS V2R1, it was time to update my app. Never having programmed in REXX before, I took a short class to learn the basics of REXX and then began converting my original BCPii app to a TSO/E REXX program using the BCPii REXX samples shipped in SYS1.SAMPLIB as a guide.
My original BCPii app queried each attribute after changing it in order to verify the new value. Now, with the new and improved version of HWIQUERY in z/OS V2R1, I bundle all of the changed attributes on one HWIQUERY call at the end of each image activation profile update. Bundling allows the app to take advantage of improved internals in the HWIQUERY service in z/OS V2R1, which now makes one call to the SE to retrieve values for multiple attributes on the same HWIQUERY request.
While there are several factors that can affect performance, I was pleased to find that the run time of the REXX version of my BCPii app (running on z/OS V2R1) was several minutes faster than the original version of the app (running on z/OS V1R13).
Here are a few details about the inner workings of my BCPii app. The image activation profile attributes I chose to include in my app are processor settings that specify the number of each type of processor, whether a processor is shared or dedicated, the amount of storage defined on the image, whether or not WLM is allowed to change processing weight-related attributes, and if so, specific processing weights. My REXX program reads in a designated configuration file with the following format:
CPC X91 VERIFY=Y
GPS= Ziip= Zaap= ICF=2
RESERVED GPS= Ziip= Zaap= ICF=1
GPS=11 Ziip=22 Zaap=0 ICF=
RESERVED GPS=44 Ziip=4 Zaap=0 ICF=
GPSIPW=11 GPSMIN=1 GPSMAX=777
ZIIPIPW=22 ZIIPMIN=2 ZIIPMAX=88
ZAAPIPW= ZAAPMIN= ZAAPMAX=
Using this format, I can specify which CPC I want to work with, the changes I want to make to attributes in image activation profiles on that CPC, and whether I want to use BCPii to verify the changes.
Here are a few lessons I learned while creating my BCPii app:
Decide which BCPii REXX environment is best suited for your app. I initially tried using the z/OS System REXX environment, but it did not support a function that I needed - reading in a configuration file. Because you cannot pass a file name to a BCPii System REXX exec using the HWIREXX helper program, I would either have to code the AXREXX macro invocation explicitly in Assembler and forego the HWIREXX helper program, or I would need to hard-code the name of an input file in the REXX program. Neither of those options would work because I didn't want to code an Assembler helper program, and I wanted to use the same BCPii app with multiple files. My app did not call HWICMD or HWIEVENT, so the TSO/E REXX environment turned out to be the best fit for what I wanted to do.
If you receive RC=F01 HWI_AUTH_FAILURE on an HWICONN call, the system where the app is running is not authorized for the BCPii TSO/E environment. Issue command SET IKJTSO=xx, where xx is the parmlib member which contains the statement AUTHTSF NAMES(HWIC1TRX).
If you receive RC=F02 HWI_NO_SAF_AUTH on an HWISET call, the TSO userid where the app is running does not have the correct level of authority for the HWISET callable service.
If you receive RC=502 HWI_SETTYPE_VALUE_INV on an HWISET call, when reading from an input file and performing a parse var, the last variable read in is rejected by HWISET for having an invalid length. For example, “ICF=,GPSMAX=,ZIIPMAX=,ZAAPMAX=” in the sample input file above results in RC=502 from HWISET. To prevent this problem, use the REXX built-in function, STRIP (for example, x=STRIP(x)), to get the correct length of the variable before calling HWISET.
Even though you can successfully change values in an image activation profile, the image may not activate successfully with your updated values.
I am so pleased with my first BCPii app that I continue to think of new apps to write. For example, after completing the REXX app described above, I used it as a base and easily created another REXX program to change image attributes in LPAR Controls. This new app changes attribute values on a live image for WLM on/off, WLM weights, and initial capping.
Yes, it's pretty cool to be able to use REXX with BCPii for automation! If you would like to check out my BCPii REXX app, you can get a copy (unsupported, of course) from BCPii Technical Support.
Kathy Livecchi is an Advisory Software Engineer and is the z/OS System Tester for BCPii. She started her IBM career in manufacturing System Test - fixing mainframes - and now works in z/OS System Test - trying to break the operating system for several components she owns. She enjoys sports and family time.
Check out other BCPii posts on the Mainframe Insights blog: