z/VM Electronically Delivered Service (CORrective or RSU) Installation Instructions Version 7

Printable version Printable version

Instructions for z/VM Version 7 and above

  • These instructions are for installing service on Version 7 and above.
    If servicing z/VM Version 6 or earlier, instruction for servicing Version 6 should be referenced.

Electronically delivered service instructions have changed.

A new utility, GetShopz, is now available that consolidates the majority of the steps described here, and which uploads service directly to z/VM from ShopZ, if you choose to use it.

Please review the Hints that follow prior to applying service, and then select the type of service installation you want to pursue.

Service Hints

  1. Beginning with z/VM Version 7, service files are compressed differently than for prior z/VM levels, and therefore have different file names. When files are uploaded, much of the name for a received service file can be replaced with a name that is more meaningful to you. For example, a file named S001.SHOPD.S232999.SHIPDOCN.pax.z could be uploaded to VM with the name S232999.SHIPDOC, where the file name S232999 represents the order number, and the SHIPDOC is the file type. Additional file naming considerations are presented in the Upload service envelope(s) section.
  2. Two system files included with a service order have the name, GIMPAF, and are new with z/VM Version 7. These are system files that are required, but which can be ignored by users (the files are used to verify the download digital fingerprint, if the GetShopz utility is in use).
  3. Do not make any attempt to unzip or unpack received service order files on your workstation.
  4. Trying to understand your Shopz order? These Shopz headings definitions will provide a description of the order.

Direct to Host Utility

APAR VM66540 for z/VM 7.2 only (August 2021), introduced new function to simplify placing ordered service on your z/VM system.

This utility eliminates the need to store ordered service files on an interim host system (a PC), and then upload them to a z/VM system for decompression and use. The utility instead provides the ability to automatically upload selected files directly to a z/VM system, with service files decompressed as part of the upload process.

To use this utility, separately order APAR VM66540 (PTF UM35899) and install the PTF on your z/VM 7.2 system. After this service is installed, consult the GetShopz utility page for instructions on its configuration and use.

When the GetShopz utility is used to handle a service order, the processing steps consist of:

  1. Using GetShopz to transfer service files to your VM System.
  2. Installing the decompressed service envelop(s) on your z/VM Host

    After you have used GetShopz to transfer the files to z/VM, continue with Installation of service envelop(s) on z/VM

Note: The XML file shipped with your order contains the SHA1 hash value of the delivered service package, the same hash that is provided in the email from Shopz. This is automatically verified by the GetShopz utility. Verify the hash value on CMS by comparing the XML information at the bottom of the file under the label: PKGHASH hash= to the hash value provided in your download email from Shopz.

Traditional Service Download

If you are not using the GetShopz utility, or are in the process of installing the service for this utility, please continue with the instructions that follow.

After you have downloaded the VM service materials provided with your order to your workstation, you need to upload those files to your z/VM host, de-compact them and then install them. The VM service materials will be referred to as service envelope(s) throughout the rest of this document.

The remainder of this document consists of the information and sample instructions for:

  1. Upload service envelope(s) to your z/VM host from your workstation
  2. De-compacting the service envelope(s)
  3. Installing of service envelop(s) on your z/VM Host

(1) Upload Service Envelope(s)

(a) Prepare for Upload

  1. The z/VM system minidisk or SFS directory where you choose to store the service envelope(s) must be accessible by the MAINTvrm user ID, or by the installation user ID that is associated with a specific product ID (refer to applicable product Program Directory information for installation user ID specifics). The MAINTvrm 500 disk commonly is used to store uploaded service envelopes.
  2. You will need adequate, available space on the z/VM host to maintain the service envelope(s), both before and after de-compaction.

    Use the information that follows to estimate the number of 3390 cylinders or FB-512 blocks needed to hold the compacted and de-compacted service envelope(s). Note that rounding upward is advised for all division results.

    1. Multiply the number of megabytes of your compacted service envelope(s) by 1024 to determine the number of kilobytes for the envelope(s).
      Note: If the number of megabytes is less than 1MB, then use 1MB for this calculation.
    2. Divide the number of kilobytes by 4 to identify the number of 4K blocks required for storage.
    3. Divide the number of 4K blocks by 180 to determine the number of 3390 cylinders required
      or
      multiply the number of 4K blocks by 8 to determine the number of required FB-512 blocks.
    4. There is no formula to determine the space required to store de-compacted envelope file(s), but multiplying the number of required 3390 cylinders or FB-512 blocks by a factor of 5 should provide an approximate 3390 cylinder or FB-512 block size requirement.

    Example:
    For a service envelope that is approximately 27MB on the workstation, you will need approximately 195 cylinders of 3390 DASD to store both the compacted and de-compacted files.

  3. For z/VM Version 7, if you download service files using HTTP instead of Download Director, you will need to download all files before you can distinguish which of these are document files, and which are the actual service files. The names of the files that result from an HTTP download generally are vague, and by name, will identify only how many files make up the order.

    For example: 20200981162.1of3

  4. A version 7 CORective service deliverable consists of four envelope files. Two files have a file name of GIMPAF. These files need to be uploaded, but then can be ignored (they are used internally to verify file integrity after transfers). The remaining files are either documentation or actual service files.

    An RSU deliverable consists of at least two envelope files: one that provides documentation, and one or more that supply the actual RSU content.

    The files in your service order will have names that are based on the service order number, and will include naming components such as SHIPDOC.PAX (where SHIPDOC conveys an order documentation file), or SHIPTFSS.PAX or SHIPRSU.PAX (where SHIPTFSS and SHIPRSU convey actual service file content). Note also that the files you download now have an extension of PAX.z which is correct.

    Do not make any attempt to unzip or unpack these files on your workstation. Instead, just upload these via a binary transfer to z/VM.

    When files are uploaded to the z/VM host, it's advised that you assign file names that are more meaningful than an order number itself, such as DOC7103 (for the RSU documentation envelope) and RSU7103 (for the actual RSU envelope), or for a product such as DirMaint, DIRMDOC (for the COR documentation envelope) and DIRMCORS (for the actual service envelope).

    Again, the assigned VM file names can be any that are meaningful to you. When names are chosen, consider using file types such as BIN or TERSLINK, to reflect files have not yet been de-compacted. However, note that the file type SERVLINK must be used for a de-compacted file that is to be processed by the service utilities.

(b) Upload Service Envelope(s)

Upload the compacted service envelope(s) directly to z/VM, as Binary files. Note that commands that specify specific file formats or record length should not be used.

Sample Upload using TCP/IP FTP

The sample instructions that follow use FTP from a MS-DOS Window command prompt to transfer a service envelope from a workstation to a z/VM host minidisk (MDISK) or SFS directory. To use FTP, TCP/IP support must be available on both the z/VM host and the workstation host.

Note that it is not possible to FTP to a temporary MDISK on the VM host. Also, the MDISK you FTP to can not be linked in write mode by a user ID on the z/VM host. If it is linked in this manner, it must be detached before the z/VM FTP server can acquire that disk in write mode. For example, if you are logged on the MAINTvrm user ID and you want to use the MAINTvrm 500 disk to store your service files, you first need to detach the 500 disk from that user ID by entering the command:

  DETACH 500

Do this before you begin any file transfers using FTP. After all files have been uploaded, you would enter these commands to re-acquire the 500 disk:

  LINK * 500 500 MR
  ACCESS 500 C

Note: If an ESM (external security manager - e.g. IBM's RACF/VM) is enabled for the VM TCPIP FTP server then the ESM must be configured to allow the logon ID to access the required minidisks, including the minidisks owned by the logon ID. For information on how to correctly configure the FTP server and the ESM, refer to Chapter 6, "Configuring the FTP Server" and Appendix A "Using TCP/IP with an External Security Manager" in the z/VM TCP/IP Planning and Customization.

From an MS-DOS Window command prompt, type the following commands
(substitute values appropriate for your system, when they differ from
what is shown here):
 
  ftp {fully_qualifed_hostname | host ip_addr}
                                  Where "hostname" or "host ip_addr"
                                  is the VM node you want to FTP the
                                  service envelope(s) to.
 
  {type in VM userid that will receive the service envelope}
  {type in VM password}
 
        --- for sfs   ----
 
  cd {SFS_directory_name}         Where SFS_directory_name should be
                                  changed to your SFS directory name
                                  you intend to transfer to.
                                  For example: cd vmsys:userid.prodenv
 
        --- OR, for mdisk ----
 
  cd userid.mdisk_addr            Where userid.mdisk_addr should be
                                  the userid and minidisk address
                                  you intend to transfer to.  It can
                                  not be linked in write mode on the
                                  id you FTP to.  If it is then you
                                  need to detach it.
                                  If this mdisk requires a password,
                                  depending on the security manager
                                  in place on your system, you may
                                  be prompted to supply a password.
 
 lcd {drive}:\{folder}            Where "drive" is the letter, and,
                                  "folder" is name of folder, if
                                  using one, on the workstation where
                                  the service envelope exists.
                                  For example:
                                  lcd C:\vmptfs
 
 binary                           Set the transfer mode to BINARY
 
 put {fn}.bin {fn}.bin            Where "fn".bin is the name of the
                                  service envelope file on the
                                  workstation, and "fn".bin is
                                  the file to be created on the VM
                                  host.
                                  For example:
                                    put S0398768.shiptfss um98765.bin
                                    put VPTF3553.bin um98765.bin
 
      NOTE:  Depending on the size of the file and connectivity, the
             put step can take several minutes.  Make sure that the FTP
             transfer completes without errors.
 
 quit                             End the FTP session, after successful
                                  completion of all file transfers.
 

(2)De-Compaction of Service Envelope(s)

Once the service envelope(s) exist on a z/VM minidisk or SFS directory they need to be de-compacted using the DETERSE Command. Log on to the user ID you will use to install the service (usually MAINTvrm) and access the the minidisk or SFS directory that contains the service envelope files as filemode C. For example, if you stored the files on the MAINTvrm 500 disk, enter:

   ACCESS 500 C

(a) Locating the DETERSE Command

The DETERSE Command is shipped as part of the VMSES/E component of z/VM. By default, it resides on the MAINTvrm 5E6 minidisk. This disk should already be linked and accessed. If it is not, then you need to link and access it. For example:

   LINK MAINTvrm 5E6 5E6 RR
   ACCESS 5E6 B

(b) Using the DETERSE Command

The command syntax for DETERSE is:

   DETERSE ifn ift ifm ofn SERVLINK ofm (option
where option can be REPLACE. You only need to use the REPLACE option if you are going to keep the original filename and filetype of the service envelope. Otherwise no option is needed. In order for you to install the service envelope the file type must be SERVLINK. An example of using the DETERSE command is:
 
   DETERSE UM98765 BIN C UM98765 SERVLINK C

(c) Check the Service Envelope

You can verify that all the steps have completed successfully by creating a MAP file of your SERVLINK files. To create the MAP, access the minidisk or SFS directory where you have stored the SERVLINK files as filemode C and then use the command VMFPLCD to generate a MAP file:

   VMFPLCD SCAN * * ENV= fn SERVLINK C (DISK DATE EOD
 
where fn is the filename of your service envelope.
If you receive an error from VMFPLCD there is something wrong with the file and you should retrieve it again.

If the command completes successfully, it will create a file on your A disk named DISK MAP. If you will be checking several files, you may want to rename the DISK MAP file that was created to match the source of the MAP. For example, if you created a MAP for the file RSU6404 SERVLINK, you could rename the DISK MAP file to RSU6404 MAP.

The contents of the MAP file will be a list of files that are contained in the SERVLINK. Here is an example of the contents of a MAP for a corrective service SERVLINK:

   Scanning ...                 Format LRECL   Records    Date     Time
   COR      8403     U1         F         76         6  04/03/18 16:12:12
   COR      DOC      U1         F         80         8  04/03/18 16:12:12
   End-Of-Group OR End-Of-Disk
   5684042J 0100051  U1         F         80         3  04/03/18 16:12:12
   SES      MEMO     U1         F         80         2  04/03/18 16:12:12
   End-Of-Group OR End-Of-Disk
   5684042J 0100051  U1         F         80         3  04/03/18 16:12:12
   5684042J $COR8403 U1         F         76         5  04/03/18 16:12:12
   End-Of-Group OR End-Of-Disk
   5684042J $APCALL  U1         F         44         3  04/03/18 16:12:12
   5684042J $APC8403 U1         F         44         3  04/03/18 16:12:12
   5684042J $EXCALL  U1         F         44         1  04/03/18 16:12:12
   5684042J $EXC8403 U1         F         44         1  04/03/18 16:12:12
   End-Of-Group OR End-Of-Disk
   UI49994  $PTFPART U1         F         80        52  08/31/17 14:23:30
   End-Of-Group OR End-Of-Disk
   ICKSADSF CIM49994 U1         F         80     15240  08/31/17 14:23:28
   End-Of-Group OR End-Of-Disk
   End-Of-Group OR End-Of-Disk
After you have successfully created a MAP file you need to reset your SERVLINK file by entering the following command:
   VMFPLCD RST ENV= fn SERVLINK C
 
where fn is the filename of your service envelope.
You are now ready to install your service envelopes.

(3)Installation of Service Envelope(s) on z/VM

The service you ordered will either be in VMSES/E format or NON-VMSES/E format. You need to follow the appropriate instructions below based on which service you received. Files shipped with extensions of SHIPTFSS, SHIPDOCS, SHIPRSUn (where n is a number) or SHIPDOC are VMSES/E format. Files shipped with extensions of SHIPTFSN or SHIPDOCN are NON-VMSES/E.

(a) Service Envelopes in VMSES/E format

For service envelope files in VMSES/E format (files shipped with extensions of SHIPTFSS, or SHIPDOCS or SHIPRSUn or SHIPDOC):

  • Go to Chapter 3 'Installing preventive or corrective service' in the z/VM: Service Guide to install service on the VM components.
  • For IBM Licensed Products for VM (like DB2), refer to their Program Directory for the product service instructions. If the Program Directory service instructions do not mention installing from an envelope then you need to add the 'ENV fn_servlink' option to the VMFREC command (for COR service) or the VMFINS command (for RSU service). For example:
    VMFREC PPF 5999123A PRODA (ENV UM98765
    

IMPORTANT INSTALLATION NOTES

  1. The minidisk or SFS directory where you stored the service envelope files needs to be accessed as filemode C.
  2. The documentation envelope file for an RSU is a human-readable file once you DETERSE it. The documentation envelope file for COR service is a real envelope file that can (and should) be processed by the SERVICE command.

(b) Service Envelopes in NON-VMSES/E format

For service envelope files in NON-VMSES/E format (shipped with extensions of SHIPTFSN or SHIPDOCN):

You need to extract the files from the documentation service envelope first (shipped with extension of SHIPDOCN). To do that you need to enter the commands:

   VMFPLCD RST ENV= envfilename SERVLINK fm
   VMFPLCD LOAD * * A ENV= envfilename SERVLINK fm (EOD
A file with the name of SERVICE DOCUMENT should have been loaded to your A disk. You need to follow the directions in that document in order to receive and install the NON-VMSES/E service envelope file (shipped with extension of SHIPTFN).

Note: For EREP PTF application refer to the EREP Program Directory (GI10-8140), Section 3.1 Corrective Serviced (PTF).

--------------------------------------------------------------------

Last Updated: 12/05/2019