IBM Support

Updates to IMS Program Restart Facility V2.2 User's Guide and Reference (SC19-3985-04)

Product Documentation


Abstract

Updates to IMS Program Restart Facility V2.2 User's Guide and Reference (SC19-3985-04)

Content

The most recent updates appear at the top of the list.


Update 2
Date of change: April 2020
Change description: Documentation changes for APAR PH14290
Topics: Changes apply to multiple topics.

=======================================================

Topic: IMS Program Restart Facility overview > What does IMS Program Restart Facility do?

The following text has been added as the last item in the existing bulleted list:

Start of change

  • You can insert checkpoint calls dynamically into application programs that do not have any or enough checkpoint calls. By using this feature, you can add commit points to batch jobs or add checkpoint calls to application programs that require more checkpoints without having to change the programs. This capability, which is provided by the checkpoint insertion feature, can be applied to various types of applications. For example, you can use this feature when migrating programs from DLIBATCH to BMP or adding checkpoint calls to existing BMP programs.
End of change

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

Topic: IMS Program Restart Facility overview > IMS Program Restart Facility features

The following section has been added to the bottom of this topic:

Start of change

Checkpoint insertion

In a 24x7 operating environment, most of the databases in the production environment must be operable 24 hours a day for 365 days a year. Therefore, many users find it necessary to migrate their DLIBATCH programs, which are run during the maintenance period, to BMP programs, which run in IMS online systems. To release the database resources to other programs, batch programs in data-sharing environments and BMP programs that run in IMS online systems need to issue checkpoint calls more frequently than regular batch programs.

However, many DLIBATCH programs that do not assume to be run in those environments are not coded that way; they do not have any or enough processes to issue checkpoint calls. So, if you want to migrate DLIBATCH programs to BMP programs, you might need to modify those programs to add more commit points.

By using the checkpoint insertion feature of IMS Program Restart Facility, you can add checkpoint calls dynamically without having to change the programs. This feature supports applications that do or do not currently issue checkpoint calls, so you can use it on various applications, such as the programs that are to be migrated from DLIBATCH to BMP or those that require more checkpoint calls. 

For more information about the procedures and considerations on this feature, see Chapter 5, "Using IMS Program Restart Facility."

End of change

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

Topic: Product options reference 

The following topic has been added between "Symbolic parameters for log data set names" and ”IMS groups”:

Start of change

Checkpoint insertion feature options reference

By using the checkpoint insertion feature of IMS Program Restart Facility, you can add checkpoint calls dynamically without having to change the programs.

You can control how you want to use this feature by specifying the options that are documented in this section.

The following options are available for this feature:  

  • ISRTCHKP: Specifies whether you want to enable the checkpoint insertion feature.
  • PCB: Specifies which PCBs are to be used when determining the trigger for checkpoint call insertion.
  • ICPINTVL: Specifies the minimum time interval between checkpoint call insertions.
  • POS, CALLTYPE, and ICSTLST: Specifies what will be the trigger for checkpoint call insertionIf more than one of these options is specified, a checkpoint call is inserted if any of those conditions is satisfied.

ISRTCHKP=YES | NO

The ISRTCHKP option specifies whether to enable the checkpoint insertion feature. By using this feature, you can insert checkpoint calls dynamically into an application that does not have any or enough checkpoints.

Important: Enable this feature through job override options or the IRT$CNTL DD statement. It is not recommended that you enable this feature in global options unless you have in-depth understanding of all the applications that are run under IMS Program Restart Facility.  

Specify one of the following values for this option:

YES

The checkpoint insertion feature is enabled. By specifying other options described in this section, you can control how IMS Program Restart Facility behaves when running this feature.

NO 

The checkpoint insertion feature is disabled. 

The default value is NO. 

CALLTYPE=GU | NO

The CALLTYPE option specifies whether to use GU and GHU calls as the trigger for checkpoint call insertion.

Specify one of the following values for this option:

GU

GU and GHU calls are used as the trigger to insert checkpoint calls.

A checkpoint call is inserted if both of the following conditions are satisfied:

  • The time interval specified by the ICPINTVL option has passed
  • A GU call against the PCB specified by the PCB parameter ends successfully

After a checkpoint call is inserted, each database will be repositioned to its original position (before checkpoint call insertion).  

NO

GU and GHU calls are not used as the trigger to insert checkpoint calls.

The default value is NO. 

POS=ROOT | NO

The POS option specifies whether to use GN and GHN calls as the trigger for checkpoint call insertion.

Specify one of the following values for this option:

ROOT

GN and GHN calls are used as the trigger to insert checkpoint calls.

A checkpoint call is inserted if both of the following conditions are satisfied:

  • The time interval specified by the ICPINTVL option has passed
  • A GN or GHN call against the PCB specified by the PCB parameter reaches the root segment

After a checkpoint is inserted, each database will be repositioned to its original position (before checkpoint insertion). 

NO

GN and GHN calls are not used as the trigger to insert checkpoint calls.

The default value is NO. 

ICPINTVL=hhmmssth

The ICPINTVL option specifies the minimal time interval between checkpoint call insertions. IMS Program Restart Facility takes the following types of checkpoint calls into account to calculate the checkpoint interval:  

  • Checkpoint calls that were issued from within the application
  • Checkpoint calls that were issued from IMS Program Restart Facility

Important: Set an appropriate checkpoint interval to avoid too many checkpoints, which might affect the job elapsed time and system performance.

Specify the minimal time interval as an 8-digit number in the form hhmmssth, where:

        hh: hours
        mm: minutes
        ss: seconds
        t: tenths of a second
        h: hundredths of a second

For example, if you specify ICPINTVL=00050000, IMS Program Restart Facility will wait for 5 minutes after the last checkpoint call. After 5 minutes have passed, a checkpoint call will be inserted when the specified triggers occur on the specified PCB.

If you do not specify this option, the setting in the global options takes effect.

PCB= nnnn | name | * 

The PCB option specifies which PCB or PCBs will be used when determining the trigger for checkpoint call insertion. For example, if you specify PCB=PCB01, a checkpoint call is inserted if both of the following conditions are satisfied:

  • The time interval specified by the ICPINTVL option has passed
  • PCB01 satisfies any of the conditions specified by the CALLTYPE, POS, or ICSTCLST option  

Specify one or more PCBs in the following three ways:

nnnn

Specifies the PCB number in a range of 2-2500. 1 indicates the IOPCB. If you specify a PCB number, AIB calls are not used as the trigger for checkpoint call insertion. 

Important: The PCB number is the sequence number of the PCB in the generated PCB list, which does not include the PCBs for which LIST=NO was specified. For example, if the PSB definition contains an IOPCB followed by four PCBs, specify PCB=4 for the fifth PCB if the third PCB is specified with LIST=NO.

name

Specifies the PCB name.

*

Specifies that IMS Program Restart Facility uses all database PCBs to determine whether a checkpoint call should be inserted.

You cannot specify either IOPCB or GSAM PCB as the PCB parameter.  

If you do not specify this option, the setting in the global options takes effect. 

ICSTCLST=status_codes

The ICSTCLST option specifies one to five DL/I status codes. IMS Program Restart Facility inserts a checkpoint call if both of the following conditions are satisfied:

  • The time interval specified by the ICPINTVL option has passed
  • One of the specified DL/I status codes is returned from a DL/I call against the PCB specified by the PCB parameter

If you want to insert checkpoint calls only when the end of the database is reached, specify as follows:

ICSTCLST=GB

If you want to insert checkpoint calls if DL/I status code GB, FG, or FW is returned, specify as follows:

ICSTCLST=GBFGFW

You can specify up to five DL/I status codes. If you do not want to insert checkpoint calls for any specific DL/I status codes, leave this field blank.

End of change

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

Topic: Using IMS Program Restart Facility

The following topic has been added after "Stopping, holding, or restarting BMPs":

Start of change

Inserting checkpoint calls dynamically

By using the checkpoint insertion feature of IMS Program Restart Facility, you can insert checkpoint calls dynamically into application programs that do not have any or enough checkpoint calls.

Before you begin

Before using the checkpoint insertion feature, consider the following guidelines:

  • It is not recommended that you enable this feature in global options unless you have in-depth understanding of all the applications that are run under IMS Program Restart Facility. 
  • After a checkpoint call is inserted, the checkpoint insertion feature will reposition each PCB's database position, which was lost when the checkpoint call was inserted, to its original position by using the key feedback area. If the last DL/I call was unsuccessful, however, the database position might be repositioned incorrectly. For details, see "Current position after unsuccessful calls" in IMS Application Programming.
  • If a PSB has databases with non-unique keys, duplication of keys occurs in the key feedback area. This might cause incorrect database repositioning after a checkpoint call is inserted dynamically.
  • IMS Program Restart Facility inserts checkpoint calls when triggered by certain conditions, but it does not ensure successful program restarts. It is your responsibility to prepare an application logic for program restarts.
  • If an application has a ROLB call, the last commit point used in the back out processing might be a checkpoint inserted by IMS Program Restart Facility. In this circumstance, the segment returned from IMS after executing a ROLB call might be different from the one that the application has assumed to use in subsequent processing. Therefore, it is recommended that you review the application processing after the ROLB call returns control to the application program.
  • Insertion of IMS checkpoints can be resource-intensive operations; it might increase system overhead and affect the job elapsed time. 
  • This feature cannot be used for the following jobs and applications:
    • Jobs that has BYPCHKP=YES specified
    • DLIBATCH jobs that use a PSB without IO PCB (CMPAT=NO)
    • Transaction-oriented BMP programs
    • Fast path applications that use high speed sequential processing (HSSP)

About this task

To restart the application programs correctly, checkpoint calls must be issued at unit of work (UOW) boundaries. When you use the checkpoint insertion feature, you must specify each option so that checkpoint calls will be issued at unit of work boundaries.

Specify appropriate parameters by referring to the following information:

Parameters and conditions for dynamic insertion of checkpoint calls

By specifying each parameter, you can insert a checkpoint call if the time interval specified by the ICPINTVL option has passed and both conditions 1 and 2 in the following table are satisfied. You can specify multiple parameters. The database positions of all the database PCBs will then be repositioned.

Parameter Condition 1: trigger DL/I call Condition 2: DL/Call results
CALLTYPE=GU A GU or GHU call against the PCB specified by the PCB parameter Status code = ' '
POS=ROOT A GN or GHN call against the PCB specified by the PCB parameter Status code = 'GB'
or
Segment level number = 01 and status code = ' ', 'GA', or 'GC'
ICSTCLST A DL/I call against the PCB specified by the PCB parameter Status code matches the value specified by the ICSTCLST parameter

For example:

If you want to issue a checkpoint call when a GN or GHN call against PCB01 reaches the root segment, specify as follows:

   PCB=PCB01
   POS=ROOT

If you want to issue a checkpoint call when a DL/I call against PCB01 returns a DL/I status code of GB, specify as follows:

   PCB=PCB01
   ICSTCLST=GB

Format of checkpoint calls to be inserted

After the application program is started, if no XRST calls are issued before the first checkpoint insertion, IMS Program Restart Facility issues a basic checkpoint call.

After the application program is started, if an XRST call is issued before the first checkpoint insertion, IMS Program Restart Facility does not issue checkpoint calls dynamically until the application program issues an extended checkpoint call. After the application program issues an extended checkpoint call, IMS Program Restart Facility issues a similar extended checkpoint call with a different checkpoint ID.

Attention: If the checkpoint insertion conditions are satisfied before the application program issues the first XRST call, IMS Program Restart Facility inserts a basic checkpoint call. When an XRST call is issued, message IRT378E is issued and a U3631 abend occurs. In this case, review and change option settings as necessary.

Checkpoint ID

Checkpoint IDs for checkpoint calls inserted dynamically are generated by the following rule:

PRFnnnnn

Here, nnnnn represents a sequential decimal number between 00000-99999. When the number reaches 99999, it starts from 00000 again.

Checkpoint IDs for checkpoint calls issued by the application program do not change.

Procedure

  1. Access the IMS Program Restart Facility primary options menu.
  2. In the appropriate JOB options entry, activate the checkpoint insertion feature by specifying ISRTCHKP=YES in the checkpoint insertion feature options.
    Attention: It is not recommended that you enable this feature in global options unless you have in-depth understanding of all the applications that are run under IMS Program Restart Facility.
  3. Use the ICPINTVL option to specify the minimal time interval between checkpoint call insertions in the form hhmmssth, where:
    hh    Hours
    mm  Minutes
    ss     Seconds
    t       Tenths of a second
    h      Hundredths of a second
  4. Use the PCB option to specify the PCBs that you want to use as the trigger for checkpoint call insertion. 
  5. Enable at least one of the following options as required by the application program.
    a. To use GU and GHU calls as the trigger, specify GU/GHU for the CALLTYPE option.
    b. To use GN and GHN calls as the trigger, specify GN/GHN for the POS option.
    c. To use specific DL/I status codes as the trigger, specify DL/I status code for the ICSTCLST option. You can specify up to five DL/I status codes.  
  6. Save the updated job options.
End of change
--------------------------------------------------------------------------

Topic: Troubleshooting > Runtime messages (IRT)

The following new messages have been added:

Start of change

IRT370W  CHECKPOINT INSERTION  REQUEST IGNORED - reason
Explanation: The request to use the checkpoint insertion feature was ignored because of the reason listed in the message. The reason can be one of the following:

  • IN= HAS BEEN SPECIFIED
  • INCORRECT PARAMETERS
  • THE SPECIFIED PCB DOES NOT EXIST
  • THE SPECIFIED PCB IS NOT A DBPCB     
  • PCB MUST BE 2-2500          
IMS Program Restart Facility does not support the checkpoint insertion feature in these circumstances.
System action: The job continues running without the checkpoint insertion feature.
User response: Review the reason for the failure, and either correct the problem or do not specify ISRTCHKP=YES for the job.

End of change

---

Start of change

IRT371W BYPASS AND CHECKPOINT INSERTION REQUESTS IGNORED - MUTUALLY EXCLUSIVE OPTIONS
Explanation: The bypass checkpoint function and the checkpoint insertion function are mutually exclusive. Specify only one of these parameters.
System action: The job continues. The ISRTCHKP and the BYPCHKP specifications are ignored.
User response: Specify either the EXPDT, EXPDL, or RETPD parameter.

End of change

---

Start of change

IRT372W ICPINTVL MUST BE IN HHMMSSTH FORMAT
Explanation: The ICPINTVL parameter was specified incorrectly.
System action: The job continues processing as if the ICPINTVL parameter was not specified.
User response: Specify an 8-digit number in the form hhmmssth, where:

  • hh represents hours
  • mm represents minutes
  • ss represents seconds
  • t represents tenths of a second
  • h represents hundredths of a second
Make the necessary correction.

End of change
---
Start of change

IRT373I CHECKPOINT INSERTION FEATURE IS ACTIVE
Explanation: Option ISRTCHKP=YES was specified, enabling the checkpoint insertion feature.
System action: The job step continues to run, inserting some checkpoint calls based on the time interval that was specified by the ICPINTVL parameter.
User response: None. This message is informational.

End of change

---

Start of change

IRT374I   CALLTYPE(xx) POS(xxxx) STATUS(xx) PCB(xxxxxxxx) ICPINTVL(xxxxxxxx
Explanation: The checkpoint insertion feature is active. This message displays the parameters related to the checkpoint insertion feature that are in effect for this job step.
System action: The job step continues running.
User response: None. This message is informational.

End of change

---

Start of change

IRT375I ICSTCLST=xxxxxxxx
Explanation: The list of status codes specified by the ICSTCLST parameter that is used by the checkpoint insertion feature is displayed.
System action: The job continues running.
User response: None. This message is informational.

End of change

---

Start of change

IRT376I TOTAL CHKP CALLS: nnnn  INSERTED: nnnn
Explanation: The checkpoint insertion feature of IMS Program Restart Facility was active during the IMS job step. This message indicates the number of checkpoint calls that were issued during the processing and the number of checkpoint calls that were inserted by the checkpoint insertion feature.
System action: None.
User response: None. This message is informational.

End of change

---

Start of change

IRT377E LOAD FAILED FOR modname - CHECKPOINT INSERTION FEATURE WILL NOT BE AVAILABLE
Explanation: An MVS LOAD failed for module modname.
System action: The checkpoint insertion feature is disabled for this job step.
User response: Review the job output for additional messages that might indicate the reason for the error.

End of change

---

Start of change

IRT378E CHECKPOINT INSERTION FAILED - text
Explanation: An error occurred while attempting to insert a checkpoint call. One of the following additional information will be displayed: 

  • CALLTYPE(xxxx) STATUS(xx) PCB ADDR(xxxxxxxx) PARM ADDR(xxxxxxxx)
  • SUBROUTINE CALL FAILED
  • PRF INSERTED BASIC CHKP BEFORE XRST CALL; REVIEW THE PARAMETERS                      
System action: The job ends abnormally with a U3631 completion code.       
User response: Contact IBM Software Support. Provide all job output for analysis.

End of change

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

Topic: Troubleshooting > ISPF messages (IRTA, IRTB, IRTC)

The following new messages have been added:

Start of change

IRTC114E ISRTCHKP Option Invalid
Long message: The ISRTCHKP value specified is not valid. The value must be either YES or NO.
System action: None.
User response: Enter a valid value for the option.

End of change

---

Start of change

IRTC115E PCB Option Invalid
Long message:The PCB value specified is not valid. The value must be one of the following: a valid PCB name, a number between 2 and 2500, an asterisk ("*"), or blank.
System action: None.
User response: Enter a valid value for the option.

End of change

---

Start of change

IRTC116E ICPINTVL Option Invalid
Long message: The ICPINTVL value specified is not valid. The value must be specified as a time interval in the form hhmmssth.
System action: None.
User response: Enter a valid value for the option.

End of change

---

Start of change

IRTC117E CALLTYPE Option Invalid
Long message: The CALLTYPE value specified is not valid. The value must be either GU or NO.
System action: None.
User response: Enter a valid value for the option.

End of change

---

Start of change

IRTC118E POS Option Invalid
Long message: The POS value specified is not valid. The value must be either ROOT or NO.  
System action: None.
User response: Enter a valid value for the option.

End of change

---

Start of change

IRTC119E ICSTCLST Option Invalid
Long message: The ICSTCLST value specified is not valid. The value must be a list of two-character status codes or blank.
System action: None.
User response: Enter a valid value for the option.

End of change

---

Start of change

IRTC120E Mutually Exclusive Options Specified 
Long message: The bypass checkpoint option (BYPCHKP) and the checkpoint insertion option (ISRTCHKP) are mutually exclusive. Specify only one of these parameters.
System action: None.
User response: Specify either the BYPCHKP or ISRTCHKP parameter.

End of change

Update 1
Date of change:
 December 2019
Change description: Documentation changes for APAR PH18911
Topics: Changes apply to multiple topics.

=======================================================

Topic: Product options reference > Global options reference

A new option, AUDTOPMD, has been added as follows:

Start of change

AUDTOPMD

Information about updates in each IMS Program Restart Facility options module is stored in the last record of each options module in the following format:

Descriptor Byte length
Type of options module     8
Reserved area     4
Julian date (hexadecimal)     4
Time (hexadecimal)     4
User ID     8
Reserved area    
variable length
 

The AUDTOPMD option determines whether to log the user ID information of the user who last updated each options module. If you update the AUDTOPMD option, the user ID field of every options module will be updated.

 

AUDTOPMD=YES | NO

YES

If you specify YES, IMS Program Restart Facility logs the date and time when each options module was last updated and the user ID of the user who last updated it.

NO

If you specify NO, IMS Program Restart Facility does not log the user ID information.

The default value is YES.

End of change

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

Topic: Troubleshooting > ISPF messages (IRTA, IRTB, IRTC)

The following message has been changed: IRTB019E

The following messages have been added: IRTC112E, IRTC113W

Start of change

IRTB019E Global Options Not Found
Long message:
options_module_name cannot be created until Global Options have been created.

System action: The request fails.
User response: Ensure that global options are defined in the IRTOPT data set before you define other options.

 

IRTC112E AUDTOPMD Option Invalid
Long message: The AUDTOPMD value specified is not valid. The value must be either YES or NO.
System action: None.
User response: Enter a valid value for the AUDTOPMD option.

 

IRTC113W AUDTOPMD Process Skipped
Long message: Global Options have been saved. However, the AUDTOPMD option processing is skipped because another TSO user is currently editing other options (options module xxxxxxxx). 
System action: None.
User response: If you do not intend to change the AUDTOPMD option, you can ignore this warning message.
If you want to change the AUDTOPMD option, wait for the other TSO user to finish editing the options, and then retry.

End of change

Publication Number

SC19-3985-04

Original Publication Date

10 November 2013

[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SSAVHR","label":"IMS Program Restart Facility for z\/OS"},"ARM Category":[{"code":"a8m0z000000cvZOAAY","label":"IMS Program Restart Facility"}],"ARM Case Number":"","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"2.2.0","Edition":""}]

Document Information

Modified date:
23 April 2020

UID

ibm10742097