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 one of the Universal Agent 7.7.x for z/OS cumulative PTF maintenance distribution files. Cumulative PTFs are packaged as a compressed tarball (`sb-v.r.m.l-zos-PTFs.tar.Z`) or as a ZIP file (`sb-v.r.m.l-zos-PTFs.zip`).
Step 2a	If the distribution files with the `.tar.Z` extension was downloaded, decompress it using any utility that can process files in Lempel-Ziv (that is, compress) format. Use tar to extract the files from the uncompressed file. To do both in a single statement, decompress the file to stdout and pipe the result to tar (for example, `zcat sb-v.r.m.l-zos-PTFs.tar.Z \| tar xvf -)`.
Step 2b	If the distribution file with the `.zip` extension was downloaded, decompress it using any utility that can process files in ZIP (or, PKZIP) format. The `.zip` file can also be extracted using Windows native file extraction tools.
Step 3	Modify the `UNVFTP-PTF.TXT` script provided by the distribution file to upload the PTF files and the JCL (which resides in `UNVRECV-PTF.JCL`) to process them. 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 `./ascii subdirectory`. Look for the #HOSTNAME, #USERID, #PSWD, and #HLQ placeholders in `UNVFTP-PTF.TXT` and set them to the appropriate values.
Step 4	Modify the JCL uploaded from `UNVRECV-PTF.JCL` and run the job to receive the cumulative PTF XMIT file.

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

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.Z

For example: sb-7.0.0.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-7.7.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. Note 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. Note 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. Note 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/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

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.7.0.1-zos.PTFs.tar.Z | tar xvf -

This decompresses and extracts the 7.7.0.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-7.7.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.

open #HOSTNAME
user #USERNAME #PASSWORD

ascii
quote site blksize=3120 recfm=fb lrecl=80 pri=1 sec=1 cyl
put UNVRECV-PTF.JCL '#HLQ.UNV.V7R2M1.RECVPTF.JCL'

;Uncomment these lines when transferring from a
;Unix- or Windows-based system.
;put ascii/UNVRECV-PTF.JCL '#HLQ.UNV.V7R2M1.RECVPTF.JCL'

bin
quote site blksize=3120 recfm=fb lrecl=80 pri=1000 sec=100 cyl
del '#HLQ.UNV.V7R2M1.PTFS.XMIT'
put UNV72101.XMT '#HLQ.UNV.V7R2M1.PTFS.XMIT'

quit

After uploading, review the comments contained in '#HLQ.UNV.V7R2M1.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.

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.V7R2M1.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 UNV6511.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)
//*********************************************************************
//* (C) COPYRIGHT 2000-2021 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.V721.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.V7R2M1.PTFS.XMIT')
    DA('#HLQ.V721.UNV.PTFS') +
    UNIT(SYSALLDA) VOL(#VOLSER) +
    CYL SPACE(750 100) RELEASE
/*
//*

Installing a Cumulative PTF File

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 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 2	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 3	Fully test the maintenance. Only after all testing is completed should you proceed to the next step.
Step 4	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.