Latest ApplyPTF #: RO79605
Last Updated: March 20, 2015
Latest ApplyPTF Readme and Download
The ApplyPTF utility allows you to apply and/or list PTFs on your system or master install image. You may either work interactively with the ApplyPTF Wizard on Microsoft Windows, or invoke it from the command line with arguments that specify the actions you wish it to perform. Working interactively with the ApplyPTF Wizard is the easiest method of applying fixes. Whenever any information has been omitted, or decisions from you are required, the ApplyPTF Wizard will prompt you as necessary. ApplyPTF can:
Notes before continuing with this document:
ApplyPTF eliminates common PTF application problems:
* Verifies prerequisite PTFs have already been installed
ApplyPTF scans through the node's "history file", a log that lists what PTFs have been applied (and when) by this application. If no such log exists it offers to create one and will name it "<nodename>.his".
More information on history files is included later in this document.
* Compares the file dates in the PTF with those already on the target
ApplyPTF compares the date stamp of all "replacement" files in the PTF with those already on the system. It will not replace a file if it detects that the new file is older than its installed counterpart.
* Backs up the original files in case you need to remove the PTF
ApplyPTF creates a directory tree "REPLACED\PTFNAME.OLD" on Microsoft Windows, and "REPLACED\PTNFAME" on Unix, in the target component/image directory. For example,
It then copies all original files that will be replaced to this directory. It will not overwrite any file already in this directory, thus not overwriting any originals if the file is replaced again in a later PTF application.
* Maintains a PTF history file for each PTF application target
ApplyPTF will update the target's history file each time it applies a PTF to it.
* Seamlessly performs all of the above actions from a single node
The ApplyPTF Wizard can be run from any Microsoft Windows node. There is a Unix version of ApplyPTF as well.
Be sure to review the installation instructions included with each PTF before using ApplyPTF to apply a fix to any system. (Some fixes may contain instructions about steps that need to be completed before or after a fix is applied.)
The ApplyPTF Wizard requires the following for Microsoft Windows:
The share can be readable if you plan only to list the PTFs applied to that node. The share must be write-enabled if you plan to apply a PTF to that node. For example, if you plan to apply a CA NSM PTF to a remote node, there must be a write-enabled share of the installation directory (typically C:\Program file\CA\<component home dir> in this case) on the remote node. You need not map this to a drive letter on your system. (If you already share the parent directory of the component directory, you don't need to share the component directory again).
The ApplyPTF Wizard requires the following for Unix:
Note: The rexec daemon must be active on the Unix machine to allow ApplyPTF to connect to Unix from Microsoft Windows. If this daemon is not running, edit the ApplyPTFunx.ini file on Microsoft Windows (located in the same directory as ApplyPTF) and change telnet=0 to telnet=1.
ApplyPTF Wizard Instructions
All CA NSM Services and processes on any Microsoft Windows target node(s) should be stopped prior to applying any PTF.
Please be sure to review the installation instructions included with each PTF before using ApplyPTF to apply a fix to any system. (Some fixes may contain instructions about steps that need to be completed before or after a fix is applied.)
You may either work interactively with the ApplyPTF Wizard, or invoke applyptf.exe from the command line with arguments that specify the actions you wish it to perform. The node name for "List the PTFs applied to the local or a remote node" and "Apply a PTF to the local or a remote node" will be default to local machine.
Working interactively with the ApplyPTF Wizard is the easiest method of applying fixes. Whenever any information has been omitted, or decisions from you are required, the ApplyPTF Wizard will prompt you as necessary.
ApplyPTF History File
The first time the ApplyPTF Wizard is asked to work with a node, it will state that it can not find a "history" file for that node and may ask if you wish to create it. Such files are always named "<nodename>.his", where nodename is the node you specified. It is generally wise to use nodenames rather than IP addresses if at all possible. For Microsoft Windows and Unix, the history file is stored in the root product directory. For AS/400, the history file is saved in the main product library, which by default is CAUNIOBJ. (You could get a large and confusing set of a.b.c.d.his files on your machine, so using the node names is recommended.)
IMPORTANT: Since you can use the ApplyPTF Wizard from any node to apply to any other node, you may create multiple history files on multiple machines for the same target node! In this event you should manually merge the files so as to keep an accurate log. This is a relatively simple task because the history log is an ASCII text file, thus you can just cut and paste multiple logs together. You can also choose to apply from only one client node and one PTF directory, in which case this will no longer be a concern.
ApplyPTF Command Line Instructions (Microsoft Windows)
Use ApplyPTF /? to display the usage and version information.
You may invoke ApplyPTF via the command line. Call applyptf.exe and use any of the following options:
/PTF=c:\path\to\PTFname.jcl or /PTF=c:\path\to\PTFname.caz /NODE=nodename /MASTER=c:\path\to\root\image\directory /LIST=nodename /LIST=PATH:c:\path\to\unix\history\file.his /MASTERLIST=c:\path\to\root\image\directory /OUTPUTFILE=c:\path\and\name\of\output\file /FILE=c:\path\to\command\file /SILENT /CREATEHISTORY /INSTALLNEW /USERNAME=userid_to_ftp_to_remote_node /PASSWORD=password_for_ftp_userid /DEBUGFILE=c:\path\and\name\of\debug\file /CONFIRMBYPASS
ApplyPTF Batch Execution (Microsoft Windows)
As mentioned above, you may execute a set of /PTF and /NODE or /MASTER or /BATCHCMD commands by using a text file, and specifying the path to that file in the ApplyPTF Wizard, or on the command line by typing:
The command file may list the /PTF= /NODE= specifications in any order regardless of operating system. Special attention should be paid to prerequisite and co-requisite definitions. The dependencies are defined in the .TXT file for each fix, and the prerequisite checking is enforced via the JCL. Be sure to apply those fixes that are prerequisites for others, first.
Any system command should be specified after /BATCHCMD=. It allows you to execute master pre and post commands.
If any required specifications are omitted or if there are problems during execution, the ApplyPTF Wizard will prompt you with the relevant information. If the /SILENT command line option is used, or if the "Non-interactive" check box is on in the ApplyPTF Wizard, all interaction will be turned off, and any requests that require user interaction will be skipped.
Note: ApplyPTF does not trap the result of any SYSCMDs, PRESYSCMDs, or BATCHCMDs.
** Sample command file for execution by the ApplyPTF Wizard: **
/PTF=c:\path\to\the\PTF.jcl /NODE=nodename /PTF=c:\path\to\another\PTF.jcl /NODE=nodename /USERNAME=id /PASSWORD=pw /PTF=c:\path\to\another\PTF.jcl /NORE=nodename /PTF=c:\path\to\another\PTF.jcl /MASTER=d:\root\directory\of\cdimage /BATCHCMD=cd c:\temp
Note: Any valid path is acceptable, "c" and "d" drives are just examples. ".caz" may also be specified, instead of ".jcl".
In the above example the first PTF may be for Microsoft Windows, in which case the current account must have registry and share access if the node is remote, or sufficient local access if the node is local. This is why no username/password is requested or accepted when supplied. Instead, the current user account information is used. If this were a Unix or AS/400 PTF then this line is missing the username/password fields. If interactive the user will be prompted for them, if /SILENT is on this whole request will be ignored and an error will be issued for later review.
The second PTF could be for Unix. For all such PTFs you -must- supply a valid FTP username and password to the remote machine.
The third PTF is actually the same as the second, but has a syntax error. It should be /NODE=, not /NORE=. An error message will be issued and this PTF application will be skipped.
Applying a PTF from Microsoft Windows to Unix without using the ApplyPTF Wizard
applyptfunx.exe (Microsoft Windows)
This program is a socket client responsible for sending the JCL and other fix files to the Unix host, receiving the progress messages from the host, and displaying the messages to the user. The unix executable, ApplyPTF, is started by applyptfunx.exe via a rexec (remote execute) command.
applyptfunx.exe /FILE='JCL file full path' /NODE=host /USERNAME='user id' /PASSWORD='user password' /ARCHIVE='the archive full path in unix' (e.g. /usr/tmp/tmpPTF/). [/KEEPARCHIVE=Y|N (default = N)] [/GLOBALROOT=install_path_on_unix] [/DEBUG=debug_file] [/ApplyPTFPATH=location_of_ApplyPTF_on_unix]
All arguments in the command line must be specified, otherwise error will be returned. All progress message will displayed on the stdout.
The program can be run as batch mode.
This program can be run from the command line, or it can be accessed via the applyptf.exe PTF Wizard. If run via the Wizard, all progress messages, including the data in the history file, will be displayed in the list box. If run from the command line, data will be displayed on the screen.
NOTE: If applyptf.exe or applyptfunx.exe times out when connecting to the Unix machine, you may need to set the timeout variable. The PTF_TIMEOUT environment variable can be set on Microsoft Windows to increase the connection waiting time. By default it is 1500 milliseconds. If a longer waiting time is needed, please set PTF_TIMEOUT first, then run ApplyPTF.
For example, "set PTF_TIMEOUT=5000" will set the timeout value to 10000 milliseconds, which is 10 seconds.
ApplyPTF on Unix
The default install path for the program is /usr/tmp/ApplyPTF,/ApplyPTF however it can reside in any directory. (If the default path is not used, when running applyptf.exe or applyptfunx.exe from Microsoft Windows, the path to ApplyPTF must be specified.)
The ApplyPTF program for Unix (applyptf.xxxx, and applyptf.cfg) is currently distributed with the Microsoft Windows files in a published PTF (LO77234) Please see the instructions detailed in the readme file.
The history file is created and/or modified after a PTF is successfully applied. Please refer to the "ApplyPTF History File" section in this document.
The program can be run in two modes, stand-alone and socket server.
The stand-alone version should be used if the fix is being applied locally on a Unix machine.
The version that uses socket server should be used if the fix is being applied to Unix from Microsoft Windows.
Standalone - Running ApplyPTF from the Unix Command Line
********************************************************************** applyptf -r[i][n] full-path-file-name-of-jcl [-e product-root-path][-l log-file-path] applyptf -f[i][n] full-path-file-name-of-batch-file [-l log-file-path] applyptf -m[i][n] full-path-file-name-of-jcl [-e master-image-root-path] [-c path-to-tar-file] [-l log-file-path] applyptf -b[i] [T######|LO######][QO######] [-e product-root-path] [-l log-file-path] applyptf -p[i] [T######|LO######][QO######] [-e master-image-root-path] [-l log-file-path] applyptf [-?]|["-?"] **********************************************************************
For backing out, it is necessary to specify the master/product root path.
The syntax of the batch file is:
PTF: <full path file name of jcl> [ROOT: <product root path>]
BATCHCMD and PTF can be used multiple times in any order. BATCHCMD can be used as the master pre and post commands.
The -m option allows the user to apply fixes to master images on Unix. All tar files need to be untared and saved to separate directory. The full path to the root of the master image must be specified with -e. The -c option allows the user to create a tar file after the fix is applied. The replaced files must be specified with MFILE: in the JCL file if the version is newer than Aug 3, 1999. Otherwise, files specified under FILE: will be used.
If you specify the -l option for location of the applyptf.log file, the applyptf.cfg file must also be located in that same directory.
NOTE: If applyptf.cfg is put into a directory other than /usr/tmp/ApplyPTF, the path to the log file specified using -l is also used for applyptf.cfg.
NOTE: In order to use the stand alone mode, either:
Socket Server - Executing Unix ApplyPTF from the Microsoft Windows Command Prompt
********************************************************************** ApplyPTF -s host user /usr/tmp/ApplyPTF/ApplyPTF fully_qualified_jcl_file **********************************************************************
This is the program that runs on Unix when ApplyPTF is invoked from Microsoft Windows.
The -s option runs the program as a socket server. It communicates with the Microsoft Windows client program to receive the JCL and other fix files and sends messages back to Microsoft Windows client. After the ApplyPTF operation finishes, the program will notify the Microsoft Windows client and exit. This option is not used for command line execution.
The history file is created and/or modified after a PTF is successfully applied. The history file is named [host name].his is located in the root product directory on the Unix system (i.e. /uni).
The log file is named applyptf.log and resides in the same directory as ApplyPTF. By default, this directory is /usr/tmp/applyptf. The important status log messages are also sent back to Microsoft Windows client.
In order for ApplyPTF on Microsoft Windows to apply a PTF to Unix, two things are required:
PLATFORM:Unix FILE:/ptfname.tar.Z:: FILE:/bin/myprogram:: FILE:/bin/myprogram2:: FILE:/myscript:SCRIPT: FILE:/testptf.jcl:SCRIPT:The keyword SCRIPT tells applyptfunx.exe to transfer the file in ASCII mode.
PLATFORM:Unix PRODUCT:UNIAT PREREQS: PRESYSCMD: SYSCMD: VERSION:19980701 TARFILE:/ptfname.tar.Z:: FILE:/bin/myprogram:: FILE:ABSPATH=/usr/local/CAlib/bin/myprogram:: FILE:/bin/myprogram2:CHMOD=755,CHOWN=root,CHGRP=other: FILE:/scripts/myscripts:SCRIPT: FILE:/bin/tarfileone:TARFLAG: FILE:/bin/tarfiletwo:TARFLAG:
If the VERSION: line is not specified, or specifies a version prior to 19980701, applyptf.exe will default to the old way of applying Unix PTFs. The files will be FTP'd to the user's home directory and the history file on Microsoft Windows will be updated.
The TARFILE: line specifies that the indicated file is in tar or compress format. After the PTF files are transferred to Unix, this file will be un-tar'd and/or uncompressed before the PTF is applied.
The FILE: line must specify the target path of the file with respect to the product's global root (i.e. \uni ) if there is no ABSPATH= in front of it. The ABSPATH= is used to specify the absolute path to a file.
The FILE: line must end with two colons. If keywords are specified, they must be listed between the two colons.
The CHMOD keyword tells ApplyPTF to change the permission of the file to the specified value.
The CHOWN keyword tells ApplyPTF to change the owner of the file to the specified value. If this keyword is omitted, we will query an already existing product file to determine who the owner should be.
The CHGRP keyword tells ApplyPTF to change the group of the file to the specified value. If this keyword is omitted, we will query an already existing product file to determine what the group should be.
The SCRIPT keyword tells applyptfunx.exe to transfer the file in ASCII.
The TARFLAG keyword tells ApplyPTF that this file was part of a tar file. This affects the location of this file in the archive directory. Instead of being at the root, this file may be in a subdirectory, which corresponds to the files target path.
NOTE: Newly created PTFs will contain an FTP file and an enhanced JCL file. The above instructions allow the user to update old fixes to take advantage of the new functionality of ApplyPTF. Old fixes can still be applied using the latest ApplyPTF.
Master Install Images
A master install image is a disk copy of the installation media. For Microsoft Windows, it is a copy of the Microsoft Windows install CD. For Unix, it is a copy of the Unix tar file. A master install image can be used to pre-apply maintenance prior to installing software.
Considerations for Master Install Image on Microsoft Windows:
To apply to a master image on Microsoft Windows, the full NT CD image must have been copied to some form of writeable media for PTF application to be successful. Also, cazip.exe and cazipxp.exe must exist on your machine somewhere in the path.
Considerations for Master Install Image on Unix:
NOTE: The instructions below refer to CA NSM master images.
To create the master image, you must first untar the CANSM.tar file to a master image directory (dedicated to this tar file):
tar -xvf CANSM.tar
NOTE: The CANSM tar files include additional tar files. A fix will usually need to be applied to one or more of the tar files within CANSM. For the rest of the instructions, this tar file will be referred to as IMAGE. Replace any references to IMAGE with the actual tar filename you will create a master image for.
To apply to a master image on Unix, uncompress and untar the fix file as follows:
uncompress LOxxxxx.tar.Z tar -xvf LOxxxxx.tar
Depending on what type of fix you are applying, the appropriate tar file within CANSM will need to be uncompressed and untar'd to a master image directory (dedicated to this tar file, it should not be the same as CANSM master image).
uncompress IMAGE.tar.Z tar -xvf IMAGE.taror
uncompress IMAGE.Z(some tar files do not have the .tar extension)
tar -xvf IMAGE
Apply the fix to the IMAGE master image, you must run ApplyPTF on Unix, as follows:
/<path to applyptf>/applyptf -m /<path to jcl>/LOxxxxx.jcl -e /<master root path of IMAGE>
Once this is complete, delete the IMAGE.tar or IMAGE file if it is in your IMAGE master image directory. Delete the IMAGE.tar.Z or IMAGE.Z (IMAGE.tar or IMAGE if you used uncompress for this file) file that is in your CA NSM master image directory. You must re-tar this file (to the CA NSM master image directory) from the IMAGE master image directory and then compress the file as follows:
tar -cvf /<full path to CANSM master image root>/IMAGE.tar * compress /<full path to CANSM master image root>/IMAGE.taror
tar -cvf /<full path to CANSM master image root>/IMAGE * compress /<full path to CANSM master image root>/IMAGE
NOTE: The compress command should create the file as IMAGE.tar.Z or IMAGE.Z.
You must now re-tar the CANSM file to the directory that will have setupTNG:
tar -cvf /<directory with setupTNG>/AGENT*.tar *or
tar -cvf /<directory with setupTNG>/TNG22.tar *
This repackages the CANSM file and does not require any manual steps during the install. If you are installing on more than one machine, you must use the CANSM.tar file that you have repackaged.
JCL File Explanation
PLATFORM: Operating system where the PTF is to be applied.
PRODUCT: Main product the PTF is for (UNIAT and UNIEM). This is used to determine where the files will reside on the target machine.
VERSION: This line tells ApplyPTF to expect an enhanced JCL file.
RELEASE: This line tells ApplyPTF for what release of the PRODUCT: this PTF is written.
GENLEVEL: This line tells ApplyPTF for what genlevel of the PRODUCT: this PTF is written.
PRESYSCMD: This line specifies a system command that will be run before all files are replaced. This can be used to run an update script that we ship. Variables may be used, however these variables must already be set on the target machine. This option is available for Microsoft Windows and Unix fixes.
PREREQS: This line specifies the prerequisite PTFs that are needed. If the prerequisites are not found in the history file, ApplyPTF will not allow the application of this PTF to continue.
MPREREQS: This line specifies the prerequisites needed if installing this fix to a master image. In most cases, the PTFs specified as PREREQS will also be MPREREQS. Note: Currently, MPREREQS is only valid for Microsoft Windows PTFS for certain TNG products.
FILE: This line specifies a file to be applied to a standard install. This line supports keywords:
MFILE: This line specifies a file to be applied to a master image. This line supports keywords:
TARFILE: This line specifies a file that is of the form *.tar.Z. This file contains one or more files to be replaced on the target system (Unix only see TARFLAG: above). When this file is created on a Unix box, the contained files must exist in the same directory structure that will be used on the target machine. The path of the file inside the *.tar.Z file must be the same path listed on the FILE: line.
SYSCMD: This line specifies a system command that will be run after all files are replaced. This can be used to run an update script that we ship. Variables may be used, however these variables must already be set on the target machine. This option is available for Microsoft Windows and Unix fixes.
FTP File Explanation
The FTP File (Unix only)
The FTP file is used when a Unix PTF is applied from Microsoft Windows. The FTP file tells ApplyPTF what files to transfer to the Unix box, and how. It has a similar format as the JCL file.
You can try to resolve the "cannot create socket" error when applying a fix from Microsoft Windows to Unix by changing "telnet=0" to "telnet=1" in applyptfunx.ini which can be found in the same folder as applyptf.exe on Microsoft Windows.