z/OS Installation - Cumulative PTF Maintenance
This page describes the procedures for installing a cumulative PTF maintenance for Universal Agent for z/OS.
Installation Procedures
Installation of a cumulative PTF maintenance is comprised of the following procedures:
Step 1 | Download a Universal Agent for z/OS cumulative PTF maintenance distribution file that corresponds to your currently-installed Agent version. For example, if you have Universal Agent 8.0.0.0 installed, download the PTF distribution file for version 8.0.0.x, where 'x' is the maintenance level. Before applying any maintenance for a given release, you must have the base release installed. For example, before applying any 8.0.0.x maintenance, you must have completed the Universal Agent 8.0.0.0 installation. Cumulative PTFs are packaged as a compressed tarball ( |
|---|---|
Step 2a | If the distribution files with the If the older distribution files with the |
Step 2b | If the distribution file with the |
Step 3 | Modify the Two versions of these files are included in the distribution file. The files in the main directory are EBCDIC-encoded files. ASCII-encoded versions of these files are in the |
Step 4 | Modify the JCL uploaded from info This is a new file included in PTF distributions starting with the following maintenance releases:
Starting with these releases, all components subject to change after an initial .0 release will be provided in each maintenance delivery. This includes:
You may not need to run this job included in this file every time you apply PTF maintenance. See detailed instructions below for more information. |
Step 5 | Modify the JCL uploaded from |
Cumulative PTF Maintenance Distribution File
To obtain a cumulative PTF maintenance, you must download the corresponding z/OS - PTFs package from the Stonebranch Customer Portal.
A customer user name and password - provided by Stonebranch, Inc. - are required to access this area.
Compressed Archive - .gz extension
This distribution file is a compressed TAR file that contains the cumulative PTFs in TSO TRANSMIT format, along with supporting files used to upload and receive the cumulative PTFs.
This file uses the following naming convention:
sb-Version.Release.Modification Level.Maintenance Level-operating system-PTFs.tar.gz
For example: sb-8.0.0.1-zos-PTFs.tar.gz.
The cumulative PTF XMIT dataset can be allocated and uploaded using the sample UNVFTP-PTF.TXT, and the sample JCL provided in UNVRECV-PTF.JCL can be used to do a TSO RECEIVE on the uploaded dataset.
Compressed Archive - .Z extension
This distribution file is used prior to the UA 7.9.0.0 release and is a compressed TAR file that contains the cumulative PTFs in TSO TRANSMIT format, along with supporting files used to upload and receive the cumulative PTFs.
This file uses the following naming convention:
sb-Version.Release.Modification Level.Maintenance Level-operating system-PTFs.tar.Z
For example: sb-7.8.3.1-zos-PTFs.tar.Z.
The cumulative PTF XMIT dataset can be allocated and uploaded using the sample UNVFTP-PTF.TXT, and the sample JCL provided in UNVRECV-PTF.JCL can be used to do a TSO RECEIVE on the uploaded dataset.
ZIP Archive
The ZIP version of the z/OS Universal Agent cumulative PTF distribution files have the same contents as their compressed archive counterparts and use the following naming convention:
sb-Version.Release.Modification Level.Maintenance Level-operating system-PTFs.zip
For example: sb-8.0.0.1-zos-PTFs.zip.
To unzip the file, use a third-party ZIP-based extraction application or the native Windows file extraction tool available from Windows Explorer.
For example, to extract the files using Windows File Explorer (or just Windows Explorer in some older Windows versions), right-click on the file name, select Extract All from the pop-up menu, and follow the instructions.
Distribution File Contents
The following table lists the files included in the Universal Agent for z/OS cumulative PTF distribution files.
File Name | Description |
|---|---|
README.TXT | Contains instructions for preparing and executing the install. info This is an EBCDIC-encoded text file. |
UNVFTP-PTF.TXT | A sample FTP script that allocates and transfers datasets used to store the distribution file's contents on the z/OS system. info This is an EBCDIC-encoded text file. |
UNVMT00.JCL | JCL that is available starting with the following maintenance releases:
As noted above, these releases provide components subject to change after an initial .0 release. This means that that SMP/E install datasets allocated prior to these releases may not be large enough to accommodate the increased space requirements these newer PTF distributions may have. The JCL in this file is transferred to the z/OS system by the UNVFTP-PTF.TXT script. The JCL in this file does the following:
Failure to run the UNVMT00 job may result in space-related abends when executing the UNVMTAPL or UNVMTACC jobs. Failure to run the new UNVMTPRE job may result in space-related failures when running the UNVMTRCV job. info This is an EBCDIC-encoded text file. |
UNVRECV-PTF.JCL | Sample JCL that may be used to execute a TSO RECEIVE on the uploaded UNVVRMxx.XMT file. The JCL in this file is transferred to the z/OS system by the UNVFTP-PTF.TXT script. info This is an EBCDIC-encoded text file. |
UNVVRMxx.XMT | A file in TSO TRANSMIT format that contains cumulative PTF file for the Universal Agent release identified by VRM (version, release, modification). 'xx' is a sequential number starting at 01. |
ascii/README.TXT | An ASCII-encoded copy of README.TXT. |
ascii/UNVFTP-PTF.TXT | An ASCII-encoded copy of UNVFTP-PTF.TXT. |
ascii/UNVMT00.JCL | An ASCII-encoded copy of UNVMT00.JCL. info Please read the description of the UNVMT00.JCL file, above, for important information before applying PTF maintenance. |
ascii/UNVRECV-PTF.JCL | An ASCII-encoded copy of UNVRECV-PTF.JCL. |
Transferring a Cumulative PTF File to z/OS
After downloading the distribution file to your workstation, you must extract the files and transfer them to the z/OS system upon which Universal Agent for z/OS is installed.
Follow the steps below to transfer the distribution file's contents to the z/OS system.
- Extract the cumulative PTF file from the distribution file.
- Transfer the cumulative PTF file.
- Receive the cumulative PTF file.
Extract the Cumulative PTF Files
Each version of the Universal Agent for z/OS cumulative PTF distribution file is available in two formats:
- Compressed archive
- Compressed .zip file.
The contents of both files are the same. The different formats are provided for flexibility.
Compressed Archive - .gz extension
This file can be decompressed using any utility that can process files created using the GNU zip (that is, gzip) algorithm. The decompressed file's contents can be extracted using tar.
For example:
gunzip sb-8.0.0.1-zos.PTFs.tar.gz | tar xvf -
This decompresses and extracts the 8.0.0.1 Universal Agent for z/OS distribution file that contains the cumulative PTF file on a UNIX-based system.
Compressed Archive - .Z extension
This file can be decompressed using any utility that can process files in Lempel-Ziv (that is, compress) format. The decompressed file's contents can be extracted using tar.
For example:
zcat sb-7.8.3.1-zos.PTFs.tar.Z | tar xvf -
This decompresses and extracts the 7.8.3.1 Universal Agent for z/OS distribution file that contains the cumulative PTF file on a UNIX-based system.
ZIP Archive
This file (for example, sb-8.0.0.1-zos-PTFs.zip) can be decompressed using any utility that can process files in ZIP (or, PKZIP) format.
To unzip the file, use a third-party ZIP-based extraction application or the native Windows file extraction tool available from Windows Explorer.
For example, to extract the files using Windows' File Explorer (or just Windows Explorer in some older Windows versions), right-click on the file name, select Extract All from the pop-up menu, and follow the instructions.
Transfer the Cumulative PTF Files
For the .XMT file(s), a binary transfer must be performed; otherwise, the XMIT data set(s) will not unpack correctly.
For the .JCL file, a text transfer must be performed.
Due to the numerous file transfer products available on the market, it is impractical to provide instructions for them all. FTP is one of the most popular, and the UNVFTP.TXT file included in the distribution file is a sample script that can be used as a reference to customize the transfer to your environment.
If you want to use UNVFTP-PTF.TXT (see the sample FTP script, below), begin by making the following changes:
Step 1 | Change #HOSTNAME to the z/OS host name or IP address. |
|---|---|
Step 2 | Change #USERNAME to a z/OS user ID that has updated access to the XMIT data sets being updated. |
Step 3 | Change #PASSWORD to the z/OS user ID's password. |
Step 4 | Change #HLQ to the data set high level qualifier used to allocate the XMIT data sets. |
In the examples below, all references to VvRrMl will be replaced by the appropriate Universal Agent version prior to packaging.
open #HOSTNAME
user #USERNAME #PASSWORD
quote site blksize=3120 recfm=fb lrecl=80 pri=1 sec=1 cyl
;Remove the following 2 lines when tranferring from a Unix- or Windows-based system.
bin
put UNVRECV-PTF.JCL '#HLQ.UNV.VvRrMl.RECVPTF.JCL'
;Uncomment these lines when transferring from a Unix- or Windows-based system.
;ascii
;put ascii/UNVRECV-PTF.JCL '#HLQ.UNV.VvRrMl.RECVPTF.JCL'
quote site blksize=3120 recfm=fb lrecl=80 pri=1 sec=1 cyl
;Remove the following 2 lines when tranferring from a Unix- or Windows-based system.
bin
put UNVMT00.JCL '#HLQ.UNV.VvRrMl.UNVMT00.JCL'
;Uncomment these lines when transferring from a Unix- or Windows-based system.
;ascii
;put ascii/UNVMT00.JCL '#HLQ.UNV.VvRrMl.UNVMT00.JCL'
bin
quote site blksize=3120 recfm=fb lrecl=80 pri=1000 sec=100 cyl
del '#HLQ.UNV.VvRrMl.PTFS.XMIT'
put UNV72101.XMT '#HLQ.UNV.VvRrMl.PTFS.XMIT'
quit
After uploading, review the comments contained in '#HLQ.UNV.VvRrMl.RECVPTF.JCL' and make the necessary changes. Submit the job to receive and restore the install file.
Carefully review the FTP output to confirm that the file is transferred successfully.
Prepare the SMP/E Datasets to Receive PTFs for All Components
As noted above, starting with the following maintenance releases:
- UA 8.0.0.1
- UA 7.9.2.3
- UA 7.8.3.4
- UA 7.7.2.4
PTFs for all components and other artifacts subject to change are included in the cumulative PTF distribution files. This means that the SMP/E datasets used to receive and process PTFs must be prepared to receive these larger PTFs.
A critical step to ensure successful installation of these PTFs is to run the UNVMT00 job, uploaded to the #HLQ.UNV.VvRrMl.UNVMT00.JCL dataset by the UNVFTP-PTF.TXT script. This job performs the following functions:
- Adds a new job,
UNVMTPREto the#IHLQ.UNV.VvRrMl.INSTALLdataset. This job backs up, deletes, and expands the#SHLQ.UNV.SMP.SMPPTSdataset created when the original 8.0, 7.9, 7.8, or 7.7 release was installed. TheUNVMTRCVjob stores PTFs in this SMPPTS dataset for SMP/E APPLY and ACCEPT processing. - Replaces the
UNVSMPEJCL procedure the Universal Agent installs to the#IHLQ..UNV.VvRrMl.INSTALLdataset. The updated procedure increases the space allocated to SMP/E work datasets.
A sample UNVMT00.JCL, pulled from the UA 7.9.2.3 maintenance release is shown below. Be sure to replace the #IHLQ, #SHLQ, and #SMPVOL placeholders with the appropriate values for your install before running the job.
//UNVMT00 JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,COND=(0,NE)
//*********************************************************************
//* Copyright (c) 2000-2026 Stonebranch, Inc. All rights reserved.
//*
//* Stonebranch, Inc.
//* Universal Products
//*
//* FILE: UNVMT00
//*
//* Description
//* -----------
//* This job updates an existing &HLQ..UNV.V7R9M2.INSTALL
//* dataset by adding 1 new member, UNVMTPRE, and replacing an
//* existing member UNVSMPE.
//* These members perform the following functions:
//* UNVMTPRE - reallocates the #SHLQ.UNV.SMP.SMPPTS
//* dataset to accommodate larger PTF sizes. The
//* existing dataset is backed up and restored to
//* the new, expanded dataset.
//* UNVSMPE - this is a JCL procedure used by the jobs run
//* for new installs, upgrades, and maintenance.
//* It executes the GIMDTS program to perform
//* SMPE functions. The change delivered by this
//* job is to increase the allocation used for
//* SMPE work datasets, in order to accomodate
//* larger PTF distributions.
//*
//* Prior to submitting this job, the JCL should be customized
//* to meet local requirements as described in the "Modifications"
//* section below.
//*
//* The JCL is added to the existing PDS using the IEBUPDTE
//* utility. Any members that already exist are replaced.
//*
//* Each and every step of this job must end with a condition code
//* of 0.
//*
//* Note, that If you wish to change your JCL customizations after
//* submitting this job, make the corrections in this member and
//* submit the job again. All members are replaced.
//*
//* Modifications
//* -------------
//* The JCL within this member must be customized to meet your local
//* requirements. To facilitate the customizations, the JCL contains
//* tags that are easily changed with the ISPF Edit CHANGE command.
//* From the primary command line, enter the CHANGE command
//* "C TAG VALUE ALL" to change all values of 'TAG' to 'VALUE'. This
//* must be done for each of the customization tags. All tag values
//* must be upper case.
//*
//* NOTE: These are the same placeholders used for the #SETUP member
//* of the UNV.V7R9M2.INSTALL PDS. Refer to PDS and member
//* for values used.
//*
//* Customization Tags:
//*
//* #IHLQ
//* The high-level qualifier of this data set. For example:
//* #IHLQ.UNV.V7R9M2.INSTALL.
//*
//* #SHLQ
//* The high-level qualifier of the SMP/E data sets and the
//* product target and distribution data sets. For example:
//* #SHLQ.UNV.SMP.SMPPTS.
//*
//* #SMPVOL
//* The DASD volume serial name on which the current
//* UNV.SMP.SMPPTS PDS resides. For example: VOL=SER=#SMPVOL.
//*
//*********************************************************************
//*
//ADDJCL EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD DISP=OLD,DSN=#IHLQ.UNV.V7R9M2.INSTALL
//SYSUT2 DD DISP=OLD,DSN=#IHLQ.UNV.V7R9M2.INSTALL
//SYSIN DD DATA,DLM=$$
./ ADD LIST=ALL,NAME=UNVMTPRE
//UNVMTPRE JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),
// NOTIFY=&SYSUID
//*********************************************************************
//* COPYRIGHT (C) 2000-2026 STONEBRANCH, INC. ALL RIGHTS RESERVED.
//*
//* STONEBRANCH, INC.
//* UNIVERSAL PRODUCTS
//*
//* FILE: INSTALL(UNVMTPRE)
//*
//* DESCRIPTION
//* -----------
//* THIS IS A PRE-REQUISITE JOB TO BE RUN PRIOR TO UNVMTRCV WHEN
//* APPLYING UNIVERSAL AGENT PRODUCT MAINTENANCE VIA PTFS.
//* NOTE THAT THIS JOB ONLY NEEDS TO BE RUN ONCE AND DOES NOT APPLY
//* TO ALL MAINTENANCE RELEASES. REFER TO THE USER DOCUMENTATION FOR
//* COMPLETE INSTRUCTIONS.
//*
//* THIS JOB INCREASES THE SPACE ALLOCATION FOR #SHLQ.UNV.SMP.SMPPTS,
//* ALLOCATED IN THE UNVIN01 INSTALL JOB.
//*
//* EACH AND EVERY STEP MUST END WITH A CONDITION CODE OF 0.
//*********************************************************************
//*
//* JCLLIB ORDER=#IHLQ.UNV.V7R9M2.INSTALL
//*
//********************************************************************
//* COPY THE ORIGINAL DATASET.
//* PRESERVE THE EXISTING DCB ATTRIBUTES. CHECK THE SPACE USED
//* BY THE CURRENT DATASET TO CONFIRM ALLOCATION OF THE BACKUP.
//********************************************************************
//BACKUP EXEC PGM=IEBCOPY
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD DISP=OLD,DSN=#SHLQ.UNV.SMP.SMPPTS
//SYSUT2 DD DSN=&&PTSBKUP,
// DISP=(NEW,PASS),
// DCB=#SHLQ.UNV.SMP.SMPPTS,
// SPACE=(TRK,(4500,150,50)),UNIT=SYSDA
//SYSIN DD DUMMY
//*
//********************************************************************
//* DELETE CURRENT DATASET
//********************************************************************
//DELCURR EXEC PGM=IDCAMS,COND=(0,NE,BACKUP)
//SYSPRINT DD SYSOUT=*
//SYSIN DD *,SYMBOLS=JCLONLY
DELETE #SHLQ.UNV.SMP.SMPPTS
//*
//********************************************************************
//* EXPAND THE ORIGINAL DATASET.
//* POPULATE THE NEW DATASET WITH THE COPY OF THE BACKUP DATASET.
//********************************************************************
//EXPAND EXEC PGM=IEBCOPY,COND=(8,LT,DELCURR)
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD DISP=(OLD,DELETE),DSN=&&PTSBKUP
//SYSUT2 DD DSN=#SHLQ.UNV.SMP.SMPPTS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=SYSALLDA,VOL=SER=#SMPVOL,
// DCB=(DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=3120),
// SPACE=(CYL,(500,50,50))
//SYSIN DD DUMMY
//*
./ ADD LIST=ALL,NAME=UNVSMPE
//*********************************************************************
//* COPYRIGHT (C) 2000-2026 STONEBRANCH, INC. ALL RIGHTS RESERVED.
//*
//* STONEBRANCH, INC.
//* UNIVERSAL PRODUCTS
//*
//* FILE: INSTALL(UNVSMPE)
//*
//* DESCRIPTION
//* -----------
//* UNIVERSAL PRODUCTS SMP/E JCL PROC.
//*********************************************************************
//UNVSMPE PROC
//*
//SMP EXEC PGM=GIMSMP,REGION=100M
//*
//SMPCSI DD DSN=#SHLQ.UNV.SMP.CSI,DISP=SHR
//*
//SMPOUT DD SYSOUT=*
//SMPRPT DD SYSOUT=*
//SMPLIST DD SYSOUT=*
//*
//SMPWRK1 DD UNIT=SYSDA,SPACE=(CYL,(50,5,10)),DISP=(,DELETE),
// DCB=BLKSIZE=6160
//SMPWRK2 DD UNIT=SYSDA,SPACE=(CYL,(50,5,10)),DISP=(,DELETE),
// DCB=BLKSIZE=6160
//SMPWRK3 DD UNIT=SYSDA,SPACE=(CYL,(75,25,15)),DISP=(,DELETE),
// DCB=BLKSIZE=3120
//SMPWRK4 DD UNIT=SYSDA,SPACE=(CYL,(50,5,10)),DISP=(,DELETE),
// DCB=BLKSIZE=3120
//SMPWRK6 DD UNIT=SYSDA,SPACE=(CYL,(200,50,20)),DISP=(,DELETE),
// DCB=BLKSIZE=6160
//*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(50,5)),DISP=(,DELETE)
//SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(50,5)),DISP=(,DELETE)
//SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(50,5)),DISP=(,DELETE)
//SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(50,5)),DISP=(,DELETE)
// PEND
./ ENDUP
$$
Receive the Cumulative PTF Datasets
After transferring the cumulative PTF file to z/OS, you must unpack it using the JCL uploaded from UNVRECV-PTF.JCL (which should now reside in #HLQ.UNV.VvRrMl.RECVPTF.JCL).
The sample JCL to receive and restore the cumulative PTF file, below, shows the statements contained in UNVRECV-PTF.JCL. The job performs a TSO RECEIVE on the UNVvrmll.XMT file uploaded by UNVFTP-PTF.TXT.
The JCL includes a MODIFICATIONS section at the beginning of the file that describes what JCL modifications are required prior to submitting the job. Read and complete each of the listed modifications.
Submit the job on z/OS. Return code 0 is expected.
After the data set is successfully unpacked, it is longer required and can be deleted. The files then are ready to be installed.
//UNVRECV JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),NOTIFY=&SYSUID,
// COND=(0,NE),REGION=(0M)
//*********************************************************************
//* COPYRIGHT (C) 2000-2026 STONEBRANCH, INC. ALL RIGHTS RESERVED.
//*
//* STONEBRANCH, INC.
//* UNIVERSAL PRODUCTS
//*
//* UNVRECV
//*
//* DESCRIPTION
//* -----------
//* PERFORM A TSO RECEIVE ON THE TRANSMITTED DISTRIBUTION DATA SET
//* AND A DFHSMdss RESTORE TO PREPARE FOR INSTALLATION.
//*
//* ALL STEPS MUST END WITH RC 0.
//*
//* MODIFICATIONS
//* -------------
//* 1 MODIFY THE JOB STATEMENT TO MEET LOCAL REQUIREMENTS.
//*
//* 2 CHANGE ALL '#HLQ' TO THE HIGH-LEVEL QUALIFIER OF THE
//* UNIVERSAL PRODUCTS DATA SETS.
//*
//* 3 CHANGE ALL '#VOLSER' TO THE VOLUME SERIAL NAME ON WHICH TO
//* ALLOCATE THE DISTRIBUTION DATA SETS.
//*********************************************************************
//*
//DEL00 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DELETE #HLQ.Vvrm.UNV.PTFS
SET MAXCC=0
/*
//*
//*********************************************************************
//* RECEIVE PTF DISTRIBUTION FILE
//*********************************************************************
//RECV EXEC PGM=IKJEFT01
//SYSLBC DD DISP=SHR,DSN=SYS1.BRODCAST
//SYSPROC DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTERM DD SYSOUT=*
//SYSTSIN DD *
RECEIVE INDA('#HLQ.UNV.VvRrMl.PTFS.XMIT')
DA('#HLQ.Vvrm.UNV.PTFS') +
UNIT(SYSALLDA) VOL(#VOLSER) +
CYL SPACE(750 75) RELEASE
/*
//*
Installing a Cumulative PTF File
Before installing PTF maintenance, review all the information above for the UNVMTPRE job to see whether it should be run prior to installation. It only needs to be run once, but running it with each maintenance install would not harm anything. In fact, always running it prior to installing any maintenance would be a good way to ensure you receive any future updates to the installation process.
Cumulative PTF Maintenance is installed using members UNVMTRCV, UNVMTAPL, and UNVMTACC in the INSTALL product library.
The installation itself consists of running a number of batch jobs. The output of these batch jobs should be kept until a correct installation has been verified.
Step 1 | Member UNVMTPRE applies any changes needed to support changing install requirements or procedures. Running it may be necessary to ensure success in the steps below. Change the |
|---|---|
Step 2 | Member UNVMTRCV performs an SMP/E RECEIVE of the PTFs. Change the data set allocated on ddname SMPPTFIN to the PTF data set. Modify the JCL to meet local requirements, and submit the job. |
Step 3 | Member UNVMTAPL performs an SMP/E APPLY of the PTFs. Modify the JCL to meet local requirements, and submit the job. The job should end with condition code 0. If the job does not end with condition code 0, it is most likely due to a HOLD on one of the PTFs. This is indicated by message GIM30206E printed on ddname SMPOUT. In this case, see PTF HOLDs, above. |
Step 4 | Fully test the maintenance. Only after all testing is completed should you proceed to the next step. |
Step 5 | Member UNVMTACC performs an SMP/E ACCEPT of the PTFs. Modify the JCL to meet local requirements, then submit the job. The job should end with condition code 0 or 4. If it does not, it is most likely due to a HOLD on one of the PTFs. This is indicated by message GIM30206E printed on ddname SMPOUT. In this case, see PTF HOLDs, above. |