Part 2 Ad Hoc Maintenance

Preparing for ad hoc maintenance

What is ad-hoc maintenance?

The ad-hoc maintenance process enables you to APPLY PTFs without having to perform an upgrade process, whether as a maintenance measure or a corrective measure.

After a successful ad-hoc maintenance, if you have multiple IOA environments at the same INCONTROL software level that are non-SMP/E- managed and have no ICE, you can perform a Multisystem Upgrade to update all those IOA environments.

Preparing for the ad hoc installation

The best practice is to decide carefully before beginning the ad hoc installation, which PTFs you need for your system.

Before the ad hoc installation process begins, customers must verify that there is enough space in the basepref.MAINTLIB and ilprefa.MAINTLIB libraries in order to accommodate 50 additional blocks and 4 additional directory blocks.

In preparation for the ad hoc installation, choose a method for obtaining the PTFs to be used by the ad hoc installation process. You can choose between two methods — RECEIVE ORDER from BMC's Automated Delivery Server or Obtaining PTFs from eFix.

RECEIVE ORDER

In this method, you RECEIVE the PTFs that you specify, along with any PTFs in the PRE/REQ chain that are missing from your environment, through a direct internet connection with BMC's Automated Delivery Server.

The latest Enhanced HOLDDATA is included, as well. Enhanced HOLDDATA is an SMP/E mechanism that assists in identifying PTFs in error and corrective PTFs, if available.

When using the RECEIVE ORDER method for the first time, you must perform an initial configuration. This involves setting local values for parameters regarding the required certificates and the connection with the client environment. For more information, see Parameters for RECEIVE ORDER.

Obtaining PTFs from eFix

In this method, you download PTF files from eFix. These files contain the PTFs to be installed, together with any prerequisites above the current maintenance level. After downloading the PTF files, unzip them and transfer them to the mainframe as one or more binary files. When there are multiple pages to be downloaded from eFix, each page must be downloaded as a separate file.

For each page of PTFs downloaded from eFix, if any of the PTFs are identified as being in error, a file containing SMP/E HOLDDATA statements is also included in the zip file that you download. Enhanced HOLDDATA is an SMP/E mechanism that assists in identifying PTFs that are in error, and identifying corrective PTFs, if available. These HOLDDATA files must also be transferred to the mainframe as one or more binary files. The HOLDDATA must reside in files separate from the PTFs.

These PTF and HOLDDATA files must be renamed to the names indicated in the Manage PTF(s) file(s) step of the ad hoc PTF process. They require the following dataset attributes: LRECL=80, RECFM=FB, DSORG=PS. An unlimited number of PTFs, in up to 10 files, can be installed in a single ad hoc cycle. For each PTF file, a parallel HOLDDATA file containing one or more applicable HOLDDATA statements to be RECEIVEd can also be made available.

Running ad hoc maintenance from ICE

Invoke the INCONTROL Installation and Customization Engine (ICE). For details refer to the Installation and Customization Engine section in the INCONTROL for z/OS Installation Guide: Installing.

  1. From the list on the INCONTROL Installation Options screen, select Maintain your Environment.

  2. On the IOA Maintenance and ICE refresh screen, select APPLY PTFs.

  3. Select Major Step 1, Apply Ad hoc PTFs.

Using common features

In this section, the following common procedures are described:

See Common messages reference for common messages and their explanations.

Common to both Major and Minor Step Selection panels

To select a step or an option

Enter S in the Sel column in the row next to the step or option.

To mark a step as completed

Enter C in the Sel column in the row next to the step.

Under normal circumstances, the step will be marked COMPLETE automatically.

Common to most panels for Minor Steps

To submit a job

  1. Enter S in the S column in the row next to the job description.

    The Job Status message box opens, indicating that the job is running. Pressing Enter refreshes the status and, when the job has completed, opens the job log.

    If the job ran already, a confirmation window is displayed to allow you to confirm whether you want to rerun the job (default is N=no).

  2. Press PF3 (END) to close the log.

    An OK status next to the job description indicates that the job completed successfully.

    A FAIL status next to the job description indicates that the job failed. Examine the log for the cause of the failure. To understand the information contained in the log, see Maintenance job logs.

To browse a job log

  • Enter B in the S column in the row next to the job description of a job that ran already.

Ad hoc APPLY PTF process

In the table of contents below, the primary headings (that start with the word "Step") correspond to the minor steps in the ad hoc APPLY PTF procedure in the ICE environment.

Step 1.1 – Start new ADHOC Activity

This step starts a new ad hoc PTF cycle for applying PTFs to the system.

  1. Select Minor Step 1, Start new ADHOC Activity.

    The current maintenance level and an assigned ad hoc cycle ID number are displayed.

    If the previous APPLY ad hoc PTF cycle has not yet been completed (Step 1.7 - APPLY the PTFs was started, but Step 1.12 - ACCEPT APPLYed PTFs was not reached) a message is displayed. It is recommended that you first complete the previous cycle (at least up to the ACCEPT step) before you start a new cycle.

  2. Press PF3 (END) to continue the process by returning to the Minor Steps Selection panel. To exit without continuing, enter CANCEL in the command line.

    Pressing PF3 initiates the new ad hoc PTF cycle. All log and status information from the previous cycle is deleted and it is no longer possible to return to the previous cycle.

Step 1.2 – Manage PTF(s) file(s)

  1. Select Minor Step 2, Manage PTF(s) file(s).

  2. Select the method to obtain PTFs:

    • Use RECEIVE ORDER to RECEIVE directly from BMC server

    • RECEIVE from uploaded datasets containing the PTFs — download from eFix

  3. If you chose to use RECEIVE ORDER, specify the IDs of the PTFs that you want to install.

    You do not need to specify requisite PTFs, as they will be automatically RECEIVEd together with the specified PTF(s).

    If you have not yet completed the initial configuration for RECEIVE ORDER, first enter S next to Specify 'S' to View/Edit the details of certificates/client environment for RECEIVE ORDER. On the Parameter Data Entry screen, set local values for the required/relevant parameters, as discussed in Parameters for RECEIVE ORDER, and then press PF3 (END).

    After specifying the PTF IDs, press PF3 (END) to return to the Minor Steps Selection panel.

  4. If you chose to download from eFix, perform the following steps, to check that the data sets are available with the correct attributes and names.

    1. Ensure that the PTF(s) (and HOLDDATA, if applicable) are already contained in sequential data sets on DASD. If necessary, perform the preparatory steps described in Preparing for ad hoc maintenance. In addition, ensure that the data sets that contain the PTFs have the attributes and data set names as specified in the panel instructions.

      • The name of each provided data set is displayed in the list at the bottom of the panel with a Ready status. If a parallel HOLDDATA data set was also made available, its status is displayed in the HOLDDATA column; otherwise, a status of N/A is displayed.

      • At the top of the panel, the names of the PTF and (optionally) HOLDDATA data sets to be used next (if required) are displayed.

      • There can be one or more sequential PTF data sets (limit 10). Each data set might contain one or more PTFs. For each PTF data set, a parallel HOLDDATA data set might also exist.

      • If there is no HOLDDATA for a PTF, do NOT provide an empty HOLDDATA file, since the empty HOLDDATA file might prevent Step 1.2 from completing successfully, or it might cause problems in the RECEIVE job submitted in Step 1.3.

    2. Press Enter.

      The display is refreshed, to reflect the current status of the PTF and HOLDDATA data sets.

    3. When all data sets are in Ready status, press PF3 (END) to return to the Minor Steps Selection panel.

Step 1.3 – RECEIVE and Analyze Target Environment

This step will RECEIVE the PTFs (and HOLDDATA, if applicable), then run an APPLY CHECK to analyze the target environment and prepare subsequent steps of the ad hoc cycle.

Do not run step 1.3 after step 1.7 (APPLY the PTFs) has been run.

  1. Select Minor Step 3, RECEIVE and Analyze Target Environment.

  2. Submit the job.

    A log is displayed. For general information about understanding the log, see Maintenance job logs.

  3. Examine the log for error and warning messages. Resolve any errors and rerun the job.

  4. Examine the PE PTF report, if one is included in the log.

    Do the following, as necessary:

  5. Press PF3 (END) to return to the Minor Steps Selection panel.

Step 1.4 – View content selected for installation

Use this step to review the APARs that will be installed during the ad hoc cycle.

  1. Select Minor Step 4, View content selected for installation.

    A list of APARs with a brief description is displayed.

  2. Enter S in the OP column to see the full description of an APAR. The details for each APAR are displayed in individual panels. Pressing PF3 (END) closes the panel of an APAR, allowing you to view the panel of the next selected APAR, or to return to the list.

    The S option is not active after the PTFs for the upgrade have been ACCEPTed.

  3. Press PF3 (END) to return to the Minor Steps Selection panel.

Step 1.5 – Pre-Upgrade Exception Handling

During this step you must review the exception situations relevant to this ad hoc cycle.

These are divided into two groups:

  • items that must be handled before step 1.7 – APPLY the PTFs

  • items that require reviewing and planning, but must be handled after step 1.7 – APPLY the PTFs

  1. Select Minor Step 5, Pre-Upgrade Exception Handling.

    The following groups of items are displayed:

    • Pre Installation Holds

      • Review the list of Pre-APPLY exceptions relevant to your environment. These actions must be taken before running the APPLY the PTFs step.

    • HOLD ERRORs

      • This item lists the unresolved PTF in ERROR conditions that were identified and brought to your attention during the RECEIVE and Analyze Target Environment step of this ad hoc cycle.

      • The PTF(s) listed are HELD for the ERROR Reason indicated, and the HOLD condition is NOT resolved in this ad hoc cycle. Refer to the description inHandling PE PTFs or to Step 1.3 – RECEIVE and Analyze Target Environment for instructions on how to proceed.

      • If you decide to mark this step Complete, and proceed with the APPLY step these conditions will remain unresolved.

    • Post Installation Holds

      • Review the list of Post APPLY exceptions relevant to your environment. You are being alerted to these now so that you will be aware of them and can plan for them. These activities must be done after the APPLY the PTF during the Post APPLY Exception Handling step 1.11.

    • User Exits

      • The RECEIVE and Analyze Target Environment step identified that new version(s) of exit samples, which are already implemented in your system, will be introduced by this ad hoc cycle.

      • This will not affect your system, but you should consider reinstalling these exit(s) in order to take advantage of the updates. At this point you are only alerted to this situation. The actions required to handle this will be described later in the documentation of step 1.8.

      • This item lists these user-exits.

    • Regressed Usermods

      • The elements listed were previously installed or modified in this environment by a SMP/E USERMOD, and are being replaced in this ad hoc cycle, and so the modification made by the USERMOD is being regressed.

      • Before the APPLY implementation, backup the locally modified version.

      • Following the APPLY review your modified version of the affected elements together with the new version introduced by the PTF(s) in this ad hoc cycle, and consider re-adapting and re-installing some of these USERMODS.

        There is a step in the 'Post APPLY Exception Handling' step that reminds you regarding this activity.

  2. Each item, in both categories, must be selected and reviewed in order to continue with the ad hoc PTF installation process.

  3. Once you have reviewed these, type CONFIRM to acknowledge your awareness of all required preinstallation and postinstallation activities and to assume responsibility for the SMP/E APPLY BYPASS options required to continue.

    When there are items in HOLD ERRORs, if you decide to confirm and proceed with the APPLY step, the listed errors will remain unresolved.

Step 1.6 – System Requirements

  1. Select Minor Step 6, System Requirements.

    Handle the following system requirements, before proceeding with the APPLY step:

    • Remove all INCONTROL load libraries (LOAD and SIML) from LLA, VLF, PDSMAN, QUICKFETCH, PMO, or any other fetch optimization product.

    • Shutting down all INCONTROL products in the target environment is highly recommended.

Step 1.7 – APPLY the PTFs

This step APPLYs the PTFs.

The SMP/E BYPASS options required for this APPLY, and implicitly confirmed in the Pre Upgrade Exception Handling step, are used for the APPLY process.

  1. Select Minor Step 7, APPLY the PTFs.

  2. Submit the job.

  3. When the job has completed, examine the status. If the job did not complete successfully, use B to browse the log for more details, correct the problem(s), and rerun the job until it completes successfully.

  4. Press PF3 (END) to return to the Minor Steps Selection panel.

Step 1.8 – Handle User Exit(s) Updates

This step lists the new versions of user-exit samples, introduced by the ad hoc cycle. These exits were identified as already being implemented in your system. The updates have not yet affected your system.

Select Minor Step 8, Handle User Exit(s) Updates, to display the list.

If no installed user exits were replaced by this ad hoc cycle, the following message is displayed:

Step will be marked COMPLETE. No Installed User Exits were replaced in this upgrade.

For each member in this list, consider whether you want to use the new version of the exit and if so, do the following:

  1. Back up the source of the installed exit member and its usermod job. They are both located in the ilprefa.CUSTEXIT library. The usermod job, has the same name as the sample exit name, except that the first two characters are replaced by "UM." for example, the usermod job for installing CTDX008B is UMDX008B.

  2. Enter the ICE Exit Installation Tool (Main Menu=>Customization=>Environment selection=>Product Customization (set to IOA)=>User EXITs Installation=>EXITs Customization).

  3. Enter the name of the exit member, press ENTER, and specify N on the pop-up question (Do you want to use the existing copy?).

  4. Edit the exit member source to reflect the local modifications (according to the backup) and press PF03.

  5. Specify N on the pop-up question (Do you want to use the existing Job?).

  6. Edit the job to reflect any local modifications.

  7. Submit the job and verify successful completion.

  8. After all the listed items have been handled, continue with step 1.9

Step 1.9 – Propagate Members to Environment Libs.

INCONTROL BASE libraries are shipped with members containing symbolic variables that must be resolved according to local values that are determined during installation. During the installation of INCONTROL products, members related to the products are copied from IOA libraries to the appropriate product libraries and the variables are resolved. (This process of copying elements from a BASE library to a working product library, and resolving the symbolic variables is termed propagation.)

If product members that require propagation are replaced in the BASE libraries by this ad hoc cycle, they need to be propagated to the working product libraries, for the changes to take effect. Propagation is not performed automatically - to avoid overwriting the product members (in the working libraries) that may have local modifications.

In the event that you made local modifications to the members in your working library, back up the members and, after the propagation step has been completed, reapply the modifications to the new versions of the members (based on the backups).

  1. Select Minor Step 9, Propagate Members to Environment Libs.

    If there are no members requiring propagation in the ad hoc cycle, the step is marked COMPLETE and a message to this effect is displayed. Continue with Step 1.10 – Copy Elements into Site Libraries.

  2. Enter L in the S column in the row with the Propagate selected elements description, to display a list of elements that were introduced by this ad hoc cycle and require propagation.

    A panel opens with a table listing the elements and propagation data. Statuses are displayed for the elements according to the following propagation considerations:

    • Elements that can be propagated without further analysis. There is no chance of overwriting local modifications, since they did not exist previously in the working library. These elements have a 'New' status and are pre-selected with an S (this selection cannot be removed).

    • Elements that must be propagated. There is a chance of overwriting local modifications, since they previously existed in the working library. These elements have a 'MustReplace' status and are pre-selected with an S (this selection cannot be removed). Make sure to back up the appropriate members as described above.

    • Elements that require further analysis before they are propagated. There may be a chance of overwriting local modifications, since they did exist previously in the working library. These elements have a 'Replacement' status.

    For assistance in deciding which elements to propagate or more to obtain more information about any element on the list, use the following line commands for each element:

    • B - to view the new version of the element

    • V - to read the PTF description

      The V option is not active after the PTFs for the upgrade have been ACCEPTed.

    • For the elements that are being propagated, check if there are local modifications that were made previously and must be reapplied. Back up the appropriate elements to preserve the modifications for reference.

  3. Select the elements from the list that you decide to propagate, by entering S in the O column next to the elements. Press PF3 (END) to close the panel.

  4. Submit the job.

    If you enter L after the job has completed, elements that have been propagated have a Propagated! status.

  5. When the job has completed, examine the status. If the job did not complete successfully, use B to browse the log for more details.

  6. After propagation, apply the local modifications as they existed previously using local site procedures. Use the backups that you created in step 2 as references.

  7. Press PF3 (END) to return to the Minor Steps Selection panel.

Step 1.10 – Copy Elements into Site Libraries

During the original installation, certain libraries may have been copied to libraries outside the IOA libraries and afterwards modified locally. In this step, the locally modified libraries are identified, so they can be first backed up. (Otherwise the new members in these libraries will overwrite the modified members.) When the job is run, the selected elements are copied to the site libraries. After the job has completed successfully, the local modifications must be reapplied to these members.

PROCJCL elements may be brought in an ad hoc cycle. Previously, members of the PROCJCL library may have been copied by the installation jobs to a library specified by the PROCLIB installation parameter.

If any PROCJCL members for the installed products are replaced by the ad hoc cycle, they may be listed using the L option, and selected to be recopied using the S options. If any of the selected members had local modifications in the site library, back them up first, before submitting the job, and re-work the changes after this step is completed.

  1. Select Minor Step 10, Copy Elements into Site Libraries.

    If either the PROCLIB parameter is set to the default value (DONTCOPY, do not copy to a site library), or if no PROCJCL elements are replaced in this ad hoc cycle, for the products installed, an appropriate message is issued, and the step marked COMPLETE. Continue with Step 1.11 – Post APPLY Exception Handling.

  2. Enter L in the S column in the row with the Copy selected elements description, to list the elements to be copied.

    A panel opens with a table listing the elements and copy data. For assistance in deciding with elements to copy, use the following commands:

    • B - to view the new version of the element

    • V - to read the PTF description

      The V option is not active after the PTFs for the upgrade have been ACCEPTed.

  3. Enter S in the O column next to the elements that you decide to copy and press PF3 (END) to close the panel.

    If any of these elements have local modifications, back them up now, and reapply the modifications to the new copies after the job has completed.

  4. Submit the job.

  5. When the job has completed, examine the status. If the job did not complete successfully, use B to browse the log for more details.

  6. Press PF3 (END) to return to the Minor Steps Selection panel.

Step 1.11 – Post APPLY Exception Handling

Select the post APPLY exception situations relevant to this ad hoc cycle and environment.

  1. Select Minor Step 11, Post APPLY Exception Handling.

    A panel opens with following list:

    • Post APPLY Holds

      Review the HOLD exceptions listed (if any) and take the actions described within.

    • Regressed USERMODs

      The listed elements, if any, were replaced by this ad hoc cycle. These elements were identified as having been locally modified using SMP/E USERMOD. To avoid losing the local modifications do the following:

      1. The locally modified version of these elements were backed up during the Pre-Upgrade Exception Handling step (Step 1.5).

      2. Now, compare the modified versions of each element with its new version (introduced by this ad hoc cycle).

      3. Review each element in the list and adapt it if necessary.

      4. Re-install each adapted element using an SMP/E USERMOD.

  2. Select each of the above items to review the post APPLY exception situations relevant to this ad hoc cycle and environment.

  3. Take the necessary post APPLY actions.

  4. To continue, type CONFIRM to affirm that you have taken all the required actions.

  5. Press PF3 (END) to return to the Minor Steps Selection panel.

Step 1.12 – ACCEPT APPLYed PTFs

This optional step will ACCEPT the PTFs APPLYed by this cycle.

  1. Select Minor Step 12, ACCEPT APPLYed PTFs.

  2. Submit the job.

  3. When the job has completed, examine the status. If the job did not complete successfully, use B to browse the log for more details.

  4. Press PF3 (END) to return to the Minor Steps Selection panel.

Step 1.13 – Housekeeping

The PTF and HOLDDATA files, that were used for this ad hoc PTF cycle are no longer required and are deleted in this optional step.

  1. Select Minor Step 13, Housekeeping.

  2. Press Enter to delete the PTF and HOLDDATA files.

  3. Press PF3 (END) to close the panel.