Restarting jobs

If a BMC AMI Utility fails, you must restart the job, but you do not need to make changes to it. The utility then determines that the previous run terminated prematurely and resumes processing. The utility can also auto-cleanup, leaving you the option to restart or skip the job.

Important

On restarting, you can make changes to your OUTPUT and NGTTAPE statements, but not to the utility statement. BMC AMI Utilities re-read the OUTPUT and NGTTAPE from SYSIN during a restart.

Related topic

Using-any-BMC-AMI-Utility

Serialization and concurrency between BMC AMI Utilities

To prevent two incompatible utilities from running on the same object concurrently, BMC AMI Utilities use the following mechanisms:

  • An internal matrix of utility IDs and processing objects, kept in the checkpoint.

  • The common BMC utility tables,BMCSYNC and BMCUTIL.

It is often necessary to address a previously failed utility ID before running a utility with a different utility ID on the same object. You can run the previously failed utility with a RESTART or with QUICKEXIT to clean up temporary files. If the utility is in a Must Complete state and you run a QUICKEXIT, the utility simply completes. BMC AMI Utilities ensure that restarting the job causes no damage.

Checkpoint data set

To run, BMC AMI Reorg requires access to a linear VSAM data set named during the installation procedure and configured with the NGTCKPT parameter. This checkpoint data set (NGTCKPT) contains all the restart information for utilities.

The checkpoint data set includes the following information:

  • List of objects to be reorganized and their status
  • Internal tables required for restart
  • List of objects being renamed
  • RUNSTATS values

For more information about the checkpoint data set, see Maintaining the BMC AMI Utilities checkpoint data set.

Utility ID considerationsBMC AMI Utilities accepts utility IDs (UID) with up to 16 characters as part of the PARM field on the JCL EXEC statement.

If BMC AMI Utilities determines that an earlier job using the same utility ID as the current job ended prematurely, then the current job proceeds based on the restart parameter that you specify:

  • RESTART—(Default) Processing resumes from the most recent successful checkpoint, which is typically the last completed table space or partition.
  • For any option specified::
    • If your choice is feasible for the utility, processing proceeds as dictated.
    • If the restart option is incompatible with the UID state, then processing does not continue.

The key to this process is the utility ID. Note the following considerations:

  • BMC AMI Utilities resumes the processing of the original set of objects. If you change the utility control statements before resubmitting the utility, the new statements are ignored.
  • Two BMC AMI Utilities steps using the same utility ID in different jobs cannot run concurrently. This can happen when two steps appear in inadvertent duplicates of the same job or in unrelated jobs that use the same utility ID. The second step to begin execution fails.

Best practice
Provide a unique UID. The default UID is the jobname, you can specify the jobname-stepname for uniqueness when there are multiple AMI utility steps.

Automatic cleanup of Utility IDs with BMC AMI Load

Managing restart with BMC AMI Load is simplified by the +CLEANUP(yes/no,rc) parameter. Load can be non-destructive, loaded to a shadow dataset, or destructive, replace the current dataset. Even LOAD RESUME SHRLEVEL NONE is non-destructive with BMC AMI Unload. Restart can also be affected by whether a discard limit is specified or not. This chart shows recommended values for +CLEANUP the state of the object, and the action required for restart.

Utility

Cleanup

Remarks

LOAD RESUME SHRLEVEL CHANGE

+CLEANUP(NO)

This is the special case; records are being INSERTed with COMMITs.
Correct data and restart, restart occurs at the last commit point.

LOAD RESUME SHRLEVEL NONE

+CLEANUP(YES,8)

UID is complete. The table data is as it was before the Load started.  
Start new when error is corrected.

LOAD REPLACE SHRLEVEL CHANGE

+CLEANUP(YES,8)

UID is complete. The table remains RW and ready to retry the Load.
Start new when error is corrected.

LOAD REPLACE SHRLEVEL REFERENCE

+CLEANUP(YES,8)

UID is complete. The table is RW and the data is as it was before the Load and ready to retry the Load.
Start new when error is corrected.

LOAD REPLACE SHRLEVEL NONE

+CLEANUP(YES,8)

UID is complete. The table data was lost because the load was not to shadow data sets. Retry until successful.
Start new when error is corrected.

Load can be affected by discarding. If there is a discard limit the load will fail at that limit and can be started over just as shown with the +CLEANUP(YES,8) options above. The discarded records are written after the tablespace load, if an error occurs during this phase, most likely when there is no discard limit, the load is complete but the discards are not written so the UID is in a Must Complete state, typically with a rc=16. 

Important

It is usually possible to restart a Load in the index build phase after the data is loaded. If you plan to do this, you must specify +CLEANUP(NO). With +CLEANUP(NO) a RESTART or QUICKEXIT is required to cleanup the UID.

Best practice
Set a +DISCARDLIMITRC(9) value higher than your +CLEANUP return code, this way when cleanup occurs your return code will warn you that the discard limit was reached.

UIDs in a Must Complete state with BMC AMI Load

BMC AMI Load can fail with a return code 16 and leave the Utility ID (UID) in a Must Complete state. This occurs when the Load phase is complete and posted to the Db2 catalog and then a failure occurred while writing the discarded records from the SYSREC to the specified DISCARDDN data set. As with other errors, correct the error and rerun the step.  

Important

if there’s an error writing out the discards, commonly insufficient space because all records are being discarded, then the discards may not be wanted. You can complete the Load without writing the discards by specifying QUICKEXIT and removing the SYSREC DD, the source of the discards.

BMC AMI Load can also end with an object in a Must Complete state due to errors during the narrow window for fastswitch/rename. In this case, no action is required other than a RESTART or QUICKEXIT of the UID.

Important

If a BMC AMI Load is in a Must Complete state due to failure during fastwitch/rename, the object will be RW/RECP preventing access.  A RESTART or QUICKEXIT will immediately complete the renames and return full RW access; a recovery is not needed.

BMC AMI Utilities have the following three options for the restart parameter when restarting the UID:

  • RESTART – Restart the UID and process any incomplete or failed objects which were not cleaned up, including any object that is in a Must Compete state.
  • QUICKEXIT – Back out failed objects and complete any object that are in a Must Complete state.
  • NORESTART – You cannot use this option if UID is in a Must Complete state, doing so will produce an error message in SYSERROR. 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*