Configuring ZMF for Java/zFS
This chapter provides instructions for setting up ChangeMan ZMF to manage Java components in zFS directories under Unix System Services.
Configure USS for ZMF
Before you can start making global and application administration entries to support Java application components, you must configure Unix System Services and your security system so that the SERNET / ZMF started task can create a secure environment in an zFS file system in USS.
The instructions in this section describe commands for z/OS Security Server RACF. If you use CA ACF2 or CA Top Secret, consult with your security administrator to determine the corresponding actions that are required in those security systems to accomplish the same objectives.
In the commands that follow, these conventions are used:
-
SERUSER is the user-id assigned to the SERNET / ZMF started task.
-
SERGRP is the RACF group assigned to the SERNET / ZMF started task.
-
/serdir is the high-level zFS directory created for user-id SERUSER.
Set ZMF User-ID Security for USS File Systems
Prior to Version 7.1, the ChangeMan ZMF Installation Guide directed you to create an OMVS segment with UID(0) for the userid assigned to the SERNET / ZMF started task. Starting with ZMF 7.1, SERNET and ChangeMan ZMF can perform all necessary USS functions with more restrictive privileges.
Adjust USS privileges for SERUSER, the user-id (owner) of SERNET / ZMF started tasks:
-
Assign a non-zero UID to SERUSER by manually assigning the next available value:
ALTERUSER SERUSER OMVS(UID(xxx)) -
Permit access for SERUSER to two resources so it can manage zFS in USS:
PERMIT BPX.SERVER CLASS(FACILITY) ID(SERUSER) ACCESS(UPDATE) PERMIT SUPERUSER.FILESYS CLASS(UNIXPRIV) ID(SERUSER) ACCESS(READ) SETROPTS RACLIST(FACILITY) REFRESH SETROPTS RACLIST(UNIXPRIV) REFRESH -
Ensure that the SERUSER default group SERGRP has a GID:
ALTERGROUP SERGRP OMVS(GID(YYY))
Note
In early editions of this manual, instructions for setting up security for USS file systems included steps to activate profile FILE.GROUPOWNER.SETGID in the UNIXPRIV class to ensure that anything created by the started task user ID inherits the started task GID. The intention was to guarantee that the entire zFS directory/file structure has consistent owner/group assignments.
It has been determined that the default behavior for USS is to propagate group ownership downwards for all directories and files that ChangeMan ZMF creates under the top level ZMF directory. Therefore, profile FILE.GROUPOWNER.SETGID is not required, and instructions for enabling it are removed from later editions of this book.
Create Top-Level Directory for ZMF zFS Files
Create a directory where ZMF can create and manage zFS directories and files. This is not necessarily the directory where baseline, promotion, and production libraries reside, but staging libraries should be created in this directory.
-
Create a top-level directory for USS files that will be managed by ChangeMan ZMF instances that are owned by user-id SERUSER:
-
Create a top level directory:
/serdir -
Change the owner and group owner of /serdir to SERUSER and SERGRP respectively, and propagate the change to all directories and files that may have been created under the top-level directory.
chown -R sert:cmntp /serdir -
Set the permission bits for /serdir to allow SERUSER and ZMF Administrators in group SERGRP to READ, WRITE and EXECUTE, and allow all others to READ EXECUTE.
chmod 755 /serdir
-
-
Create and mount the zFS data set for /serdir:
-
Create the zFS data set for /serdir.
-
Mount the zFS data set at /serdir:
MOUNT FILESYSTEM('zFS datasetname') mountpoint('/serdir') TYPE(ZFS) MODE(RDWR) AUTOMOV -
Add the mount of /serdir to the BPXPRMnn member in the primary SYS1.PARMLIB to ensure that the mount for /serdir is executed at IPL.
-
Adjust Security on zFS Files Managed by ZMF
For any path entered into ZMF Administration for baseline, production, or promotion libraries, adjust the permissions to give the ZMF started task ownership with permission 755.
Note
Exit exit program CMNEX093 makes it possible to override the ChangeMan ZMF default 755 permission for USS staging libraries. See the comments in the CMNEX093 program source delivered in the ASMSRC library.
Increase MAXPROCUSER or PROCUSERMAX
Unix System Services limits the number of simultaneous processes running under a userid (UID), even if the processes are initiated from multiple address spaces. ChangeMan ZMF can potentially create a large number of parallel processes inside USS as Java build jobs are file tailored and submitted under the ZMF UID.
The number of parallel processes per UID is limited by the MAXPROCUSER entry in BPXPRMxx. When this value is exceeded, USS fails the creation of new processes, which will cause jobs or tasks inside ZMF to fail. When creation of a process is failed, message BPXP005I is issued with a return code of 70 (unless suppressed by USS specifications).
A rough calculation for the number of processes required is:
2 * (# of parallel USS related jobs *executing* concurrently)
+ 2 * (# of concurrent ZMF users logged on)
...
If you do not want to increase the global limit using the MAXPROCUSER entry in BPXPRMxx, use the PROCUSERMAX parameter on the OMVS segment of the RACF profile for the ChangeMan ZMF userid.
ALTUSER userid OMVS(PROCUSERMAX(nnnn))
This command is described in "Unix System Services Planning", Section 3.
Enable CMNEX026 for LSH Listing
Listings from Java build processing are stored in zFS files in library type LSH. Library type LSH is coded in Java build skeletons, but it is not a reserved library type.
The following code is delivered in CMNEX026 to allocate an LSH staging library when language JAVA is processed.
*
* The following sample ensures that the zfs based listings libtype
* is allocated whenever a language name of JAVA is used
*
CLC X26$LANG,=CL8'JAVA' java language?
JNE X26$O010 .no, skip java
MVI X26$WORK,C'Y' indicate something added
MVC 0(3,R2),=CL3'LSH' alloc lsh for java
LA R2,3(,R2) bump for next entry
Follow the instructions at the top of exit program CMNEX026 to enable the exit. There is no need for you to add Java library types to table X26@LTYP. You may also like to examine CMNEX032.
Configure ZMF Global and Application Administration
This section shows you entries in ChangeMan ZMF global and application administration that are required to manage Java components and work in zFS.
When you enter zFS paths and directories for staging and baseline files, those paths should be under the exclusive control of the user-id assigned to the SERNET / ZMF started task. We recommend that the path be under the high-level directory you defined in Create Top-Level Directory for ZMF zFS Files.
The paths for production and promotion directories should also be under the exclusive control of the SERNET / ZMF started task, although your environment may require some sharing of write permission.
Global Staging Library Model zFS Name
When you check out a component that is stored in an zFS file, the staging library allocated for that component must be an zFS directory. On the Global Parameters – Part 7 of 8 panel (CMNGGP07), enter a Dev model zFS name to tell ChangeMan ZMF how to structure the staging path and directory name.
CMNGGP07 Global Parameters - Part 7 of 8
Command ===>
Staging library model dataset names
Dev model dsname . . . CMNTP.S6.????.STG6.#######
Dev model zfs name . . /cmntp/s6/????/#######/d +
"????" is placeholder for application name.
"#######" is placeholder for package number (.#000123).
zfs temp folder . . . . /u/sert/C001/tmp/s6 +
Package master . . . . CMNTP.S6.V810T06.CMNZMF.CMNPMAST
Cpnt mstr (short) . . . CMNTP.S6.V810T06.CMNZMF.CMNCMPNT
Cpnt mstr (long) . . . CMNTP.S6.V810T06.CMNZMF.CMNCMPNL
Delay file . . . . . . CMNTP.S6.V810T06.CMNZMF.CMNDELAY
Ser#parm . . . . . . . CMNTP.SER810.C6.TCPIPORT
Impact analysis . . . . CMNTP.S6.V810T06.CMNZMF.IADSP
Email server . . . . . mail.serena.com +
port . . . . . 00025
Tip
You can use the same general naming pattern you use for PDS(E) libraries, substituting a slash for each period. However, the path should start with the high-level directory you defined in the Security for zFS section of this document.
Note
ChangeMan ZMF does not use the information in the Prd model zfs name field on this panel. Instead, the Prd staging model zfs on the site Site Information - Part 2 of 2 panel (where site is a variable value) is used.
Global zFS Temporary Folder
Some component processes in ZMF create temporary files. When you are working with a package component that is stored in an zFS file, temporary files will also be zFS files.
You specify a directory path for temporary zFS files on the Global Parameters – Part 7 of 8 panel (CMNGGP07) shown above in field zfs temp folder. This field initially shows a top-level directory value of /tmp. Add at least one subdirectory to create a path where ZMF will create zFS temporary files.
zfs temp folder ===> /tmp/s4
Note
The SERNET started tasks running ChangeMan ZMF, File Tailoring started procedures initiated by ChangeMan ZMF, and users who access ChangeMan ZMF must have rights to create files in this folder.
Global Site zFS Production Staging Model DSNAME
The site Site Information – Part 2 of 2 panel (CMNGRST2) requires the PRD staging model zFS path for a remote site.
This example of the site Site Information – Part 2 of 2 panel (CMNGRST2) shows the Prd staging model zFS path for a development site, where the path is the same as the Dev model zFS name on the Global Parameters - Part 7 of 8 panel (CMNGGP07).
CMNGRST2 SERT6 Site Information - Part 2 of 2
Command ===>
ChangeMan ZMF subsytem id . . 6
Logical unit name . . . . . . BUCKS +
JES node name . . . . . . . . C001
Default unit name . . . . . . SYSDA (Generic disk unit)
Default volume serial . . . .
ChangeMan ZMF delay file . . . CMNTP.S6.V810T06.CMNZMF.CMNDELAY
Ser#parm . . . . . . . . . . . CMNTP.SER810.C6.TCPIPORT
Prd staging model dsname . . . CMNTP.S6.????.STG6.#######
Prd staging model zFS . . . . /cmntp/s6/????/#######/d +
Transmission vehicle . . . . . IEBCOPY (IEBCOPY or Other)
Time difference . . . . . . . +0000 (+/- HHMM)
IP address or DNS name . . . . +
Port . . . . . . . . . . . . .
Site job statement information:
//CMNSTART JOB ,'SERT6 SITE',
// CLASS=A,MSGCLASS=X
//*
//* SITE SERT6 JOB STATEMENTS
This example shows the Prd staging model zFS path for a remote site, where the path is different from the Dev model zFS name on the Global Parameters - Part 7 of 8 panel (CMNGGP07).
CMNGRST2 SERT6P1 Site Information - Part 2 of 2
Command ===>
ChangeMan ZMF subsytem id . . 7
Logical unit name . . . . . . BUCKS +
JES node name . . . . . . . . C001
Default unit name . . . . . . SYSDA (Generic disk unit)
Default volume serial . . . .
ChangeMan ZMF delay file . . . CMNTP.S7.V810.CMNZMF.CMNDELAY
Ser#parm . . . . . . . . . . . CMNTP.SER810.C6.TCPIPORT
Prd staging model dsname . . . CMNTP.S7.????.STG7P1.#######
Prd staging model zFS . . . . /cmntp/s6/????/#######/p1 +
Transmission vehicle . . . . . IEBCOPY (IEBCOPY or Other)
Time difference . . . . . . . +0000 (+/- HHMM)
IP address or DNS name . . . . +
Port . . . . . . . . . . . . .
Site job statement information:
//CMNSTART JOB ,'SERT6P1 SITE',
// CLASS=A,MSGCLASS=X
//*
//* SITE SERT6P1 JOB STATEMENTS
Global and Application Library Types
Define like-source, like-load, and like-PDS library types for your Java components in global and application library types. This application - Library Types Part 1 of 2 panel (CMNCLLT0) from a Java-only application shows the relationship between like-source and like-load Java library types.
CMNCLLT0 JZFS - Library Types Part 1 of 2 Row 1 to 11 of 11
Command ===> Scroll ===> CSR
Lib Order Lke Seq Defer Target Sel
type Description + type Opt
___ HTH zFS resident HTML 0 P ___ Y ___ ___
___ JAR Java Archives 0 L ___ Y ___ ___
___ JCF Java Class files 0 L ___ Y ___ ___
___ JCL Execution JCL 0 P ___ Y ___ ___
___ JCT Java JAR Build Control 0 S ___ Y JAR ___
___ JVL zFS - JAVA executable class 0 L ___ Y ___ ___
___ JVS zFS - JAVA source type 0 S ___ Y JVL ___
___ JVT zFS - text type 0 P ___ Y ___ ___
___ LSH zFS Listings 0 P ___ Y ___ ___
___ WAR Java Web Archives 0 L ___ Y ___ ___
___ WCT Java WAR Build Control 0 S ___ Y WAR ___
******************************* Bottom of data ********************************
...
Important
In some cases, library type definitions for Java components may not be intuitive because a component must be defined as like-source to initiate a build process, and the output of a build process must be defined as like-load so a source-to-load relationship can be recorded. How the library types in this example work in Java build processing is explained in Working With Java.
The global and application Library Types Part 2 of 2 panels (CMNCLLT1) generally look like this with only Data Set Type specified in Staging Dataset Attributes.
CMNCLLT1 JZFS - Library Types Part 2 of 2
Command ===>
Library type: HTH - zFS resident HTML
Like value: P Defer value: Y
Staging dataset attributes:
Generic unit name . . . . . . _________ (Generic group name or unit)
Volume serial . . . . . . . . _________ (Required if generic unspecified)
Space units . . . . . . . . . _________ (trk, cyl or blk)
Primary quantity . . . . . . _________ (In above units)
Secondary quantity . . . . . _________ (In above units)
Directory blocks . . . . . .
Record format . . . . . . . .
Record length . . . . . . . .
Block size . . . . . . . . .
Data set type . . . . . . . . ZFS (library, pds, zfs or blank)
Extended attributes . . . . . (no, opt or blank)
Save staging versions . . . . ALWAYS (always/none/prompt)
Enter "/" to select option:
__ Checkout component description
__ Checkout component activity file Library type . . . . __
...
Note
Staging Versions may be enabled for any text component, which includes zFS library types HTH, JCT, JAV, and WCT in the example provided here.
Global and Application Language and Compile Procedures
These are the only two language/procedure combinations required for Java.
CMNCLPRC JZFS - Compile Procedures Row 1 to 2 of 2
Command ===> Scroll ===> CSR
Language Procedure Description Order
___ JAVA CMNJAR Create Java archive 0
___ JAVA CMNJAVA Stage Java source 0
******************************* Bottom of data ********************************
Define the JAVA language and the procedures shown here on the global and application Language Names and Compile Procedures panels.
Application Baseline Libraries
On the application - Baseline Configuration Part 1 of 2 panel (CMNCBAS1), specify a Baseline Storage Means of H for all Java baseline repositories. Prior versions of baselined Java components are full copies, not delta decks.
CMNCBAS1 JZFS - Baseline Configuration Part 1 of 2 Row 1 to 10 of 10
Command ===> Scroll ===> CSR
Baseline
Install storage
Type Levels in prod means
__ HTH 3 N H
__ JAR 3 Y H
__ JCF 3 N H
__ JCT 3 N H
__ JVL 2 N H
__ JVS 2 N H
__ JVT 2 N H
__ LSH 3 Y H
__ WAR 3 Y H
__ WCT 3 N H
******************************* Bottom of data ********************************
...
In the example shown here, only executable library types JAR and WAR are installed in production execution libraries (directories), along with build listings in library type LSH to provide a diagnostic reference in case of a production problem.
On the application - Baseline Configuration Part 1 of 2 panel (CMNCBAS1), type line command S by a library type to display the application - Baseline Configuration Part 2 of 2 panel (CMNCBAS2) where you allocate new baseline paths and directories or verify existing directories.
CMNCBAS2 JZFS - Baseline Configuration Part 2 of 2 Row 1 to 2 of 2
Command ===> Scroll ===> CSR
Library type: JVS
Levels maintained: 2
Storage means: zFS
Lvl Dataset name + Status
__ -000 /cmntp/s6/jzfs/base/jvs/lvl-0
__ -001 /cmntp/s6/jzfs/base/jvs/lvl-1
******************************* Bottom of data ********************************
...
Caution
JAR and WAR build processing uses path names to collect files to be included. Exercise care when defining directory paths for baseline and promotion libraries. The following naming structure is common for MVS baseline libraries, but it would result in -1 and -2 level libraries being included in JAR or WAR builds.
-000 /cmntp/s4/v710/base/jzfs/jav
-001 /cmntp/s4/v710/base/jzfs/jav/lvl-1
-002 /cmntp/s4/v710/base/jzfs/jav/lvl-2
...
On the application - Baseline Configuration Part 1 of 2 panel (CMNCBAS2), type line command A next to a path name to create the path.
CMNCBAS2 JZFS - Baseline Configuration Part 2 of 2 Row 1 to 2 of 2
Command ===> Scroll ===> CSR
Library type: JVS
Levels maintained: 2
Storage means: zFS
Lvl Dataset name + Status
__ -000 /cmntp/s6/jzfs/base/jvs/lvl-0 *Allocated
A -001 /cmntp/s6/jzfs/base/jvs/lcl-1
******************************* Bottom of data ********************************
...
Note
When you allocate an zFS baseline path and directory from the application – Baseline Configuration Part 2 of 2 panel, there is no additional panel for library attributes as there is for PDS(E) library allocations.
On the application - Baseline Configuration Part 1 of 2 panel (CMNCBAS2), type line command V next to a path name to verify the path and display the zFS Information panel if the path exists.
CMNCBAS2 JZFS - Baseline Configuration Part 2 of 2 Row 1 to 2 of 2
Command ===> Scroll ===> CSR
Library type: JVS
Levels maintained: 2
Storage means: zFS
Lvl Dataset name + Status
___ -000 /cmntp/s6/jzfs/base/jvs/lvl-0 *Verified
V -001 /cmntp/s6/jzfs/base/jvs/lcl-1
******************************* Bottom of data ********************************
CMNDAIH ZFS Information
Command ===>
Pathname . . . /cmntp/s6/jzfs/base/jvs/lvl-2 +
Permissions . 755
File size . . 00008192
File owner . . SERT
Group owner . CMNTP
Created . . . 2015-03-22 21:25:49
Modified . . . 2015-03-22 21:25:49
Accessed . . . 2015-03-22 21:25:49
Link count . . 00002
Application Production Libraries
On the application - site Production Libraries panel (CMNCPRDL), specify paths for zFS components that you want copied to production execution libraries at package installation.
CMNCPRDL JZFS - SERT6 Production Libraries Row 5 to 7 of 7
Command ===> Scroll ===> CSR
Type Production dataset name +
Temporary dataset name +
Backup dataset name +
___ JVS /cmntp/s6/jzfs/prod/jvs
/cmntp/s6/nullfile
/cmntp/s6/jzfs/prod/jvs/backup
___ JVT /cmntp/s6/jzfs/prod/jvt
/cmntp/s6/nullfile
/cmntp/s6/jzfs/prod/jvt/backup
___ JVL /cmntp/s6/jzfs/prod/jvl
/cmntp/s6/nullfile
/cmntp/s6/jzfs/prod/jvl/backup
******************************* Bottom of data ********************************
...
Important
zFS components cannot be included in a temporary package. The Temporary Dataset Name is just a placeholder to satisfy ISPF panel edits.
Application Promotion Libraries
On the application/site – Promotion Libraries panel (CMNLRPM3), specify paths for test libraries you want to populate from staging directories.
CMNLRPM3 JZFS/SERT6 - Promotion Libraries Row 3 to 8 of 8
Command ===> Scroll ===> CSR
Promotion name: S6P1UT Level: 10
Syslib
Lib exclude Target libraries
__ JVS N /cmntp/s6/jzfs/prom10/jvs + Shadow
/cmntp/s6/jzfs/prom10/jvs + Library 1
+ Library 2
+ Library 3
__ JVT N /cmntp/s6/jzfs/prom10/jvt + Shadow
/cmntp/s6/jzfs/prom10/jvt + Library 1
+ Library 2
+ Library 3
__ JVL N /cmntp/s6/jzfs/prom10/jvl + Shadow
/cmntp/s6/jzfs/prom10/jvl + Library 1
+ Library 2
+ Library 3
...
Deploy Java Applications To WebSphere
ChangeMan ZMF can build a Java Web Application (EAR file) and deploy it to WebSphere on a z/OS system. Deployment means that the application is delivered to a location accessible to WebSphere, and a post-processing task uses published WebSphere APIs to refresh the running application.
ISPF file tailoring of ZMF skeleton CMNJAR generates batch job JCL to create JAR/WAR/
EAR files. Standard ZMF promotion, install, and backout skeletons deliver EAR files to a WebSphere accessible location (typically the webapps folder). Three skeletons create JCL for post-processing of delivered EAR files:
-
CMN$$WSP imbedded in promotion skeleton CMN$$PRO
-
CMN$$WSI imbedded in install skeleton CMN20
-
CMN$$WSB imbedded in backout skeleton CMN50
CMN$$WSP, CMN$$WSI and CMN$$WSB call WebSphere scripting APIs to refresh the application being updated. These skeletons must be customized for each environment to set variables for each application/libtype. The following table lists the variables that must be customized in each of these skeletons. Most of these values can be obtained from your WebSphere Application Server administrator.
| Variable | Description |
|---|---|
| WSHOST | WebSphere HOST System - The host where WebSphere is located |
| WSPORT | WebSphere SOAP port - The WebSphere SOAP port |
| WSUSER | WebSphere Administrative ID |
| WSPASS | WebSphere Administrative id password |
| WSSERVER | WebSphere Server - The WebSphere server name where the application is located |
| WSNODE | Websphere Node - The WebSphere Node name where the application is located |
| WSAPPL | WebSphere Application - The WebSphere application name |
| WSSCRIPT | Jython Script file to execute - The script file to execute. The default is zmfws.jy. The path to this file also must be updated. |
...
Also, the following details must be configured in each skeleton:
-
Configure path to wsadmin - The path to the WebSphere wsadmin tool.
-
Add component in CMN$$WSI - Component names must be added for the install skeleton.