SPICE. SPICE DL/I Product Reference Manual. Release 3.1 SPI Span Software Consultants Limited

Transcription

1 SPICE S p a n I n t e g r a t e d C h e c k p o i n t / R e s t a r t E n v i r o n m e n t SPICE DL/I Product Reference Manual Release 3.1 SPI Span Software Consultants Limited Little Moss, Peacock Lane High Legh Knutsford Cheshire WA16 6PL UNITED KINGDOM Telephone: +44 (0) Fax: +44 (0) spice@spansoftware.com website httl:// Copyright 1993, 2009 Span Software Consultants Limited. All rights reserved. No part of this publication may be re-produced, stored in a retrieval system or transmitted, in any form or by any means, electronic, mechanical, or otherwise, without the prior written consent of the publisher. 18 June 2009

2 Preface Abstract SPICE is an acronym for Span Integrated Checkpoint/Restart Environment. SPICE DL/I is a software product that simplifies the design, implementation and operation of restartable batch application programs in the IMS environment. This manual is the principal reference for SPICE DL/I. It documents the facilities available, how they can be incorporated into application programs, and how those programs should be operated. Other SPICE Manuals SPI 08 SPICE SQL Product Reference Manual This manual is the principal reference for SPICE SQL, the companion SPICE product for the DB2 environment. SPI 10 SPICE SQL & SPICE DL/I Diagnostics Reference Manual This manual is the reference for the messages and other diagnostic information issued by the SPICE products. SPI 14 SPICE SQL & SPICE DL/I Getting Started This manual is the reference for the installation of the SPICE products. Note: SPICE, SPICE DL/I, SPICE SQL, SPICE Restart API and In-Flight Restart are trademarks of Span Software Consultants Limited. IBM, IMS, DB2, CICS, z/os and OS/390 are trademarks of the International Business Machines Corporation. ii SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

3 Contents Chapter 1. Introduction to SPICE DL/I Using This Manual Introduction...2 Restartable Application Programs...3 SPICE DL/I Summary...4 SPICE Program Area Management...4 SPICE Sequential File Management...5 SPICE Checkpoint Processing...5 SPICE Automatic Restart Processing....5 SPICE In-Flight Restart...5 SPICE Application Testing...6 SPICE Checkpoint Suppression...6 SPICE Application Timeout...6 Operating SPICE and its Application Programs SPICE DL/I and SPICE SQL...7 Chapter 2. SPICE DL/I Application Programming Principles SPICE DL/I Restartable Program Organization Restartable Program Structure Simple Batch Program 10 Batch Program with Checkpoints 11 Batch Program with SPICE DL/I 12 Restartable Program Execution Program Start 13 Program Restart 13 Program Rerun 14 SPICE DL/I Programming Facilities Introduction to SPICE DL/I Programming Facilities Program Area Management Facilities Sequential File Processing Facilities Record Length Processing 16 File Record Position Processing 16 Application Testing Facilities Checkpoint Facilities Checkpoint Suppression 17 Forced Checkpoint 17 Other Considerations SPICE DL/I and DB2 17 SPICE DL/I and CICS 17 Program Design Considerations Checkpoint Considerations SPICE Checkpoint Suppression 18 Contents 18 June ,2009 Span Software Consultants Limited iii

4 Location of Checkpoint statements 18 Checkpoint Frequency 18 Forced Checkpoints 18 Post Checkpoint Processing 19 Restart Considerations Placement of XRST Statement 19 Selecting Program Data for Restart 19 Sequential File Programming Considerations Record Length Processing 20 Restart Considerations 20 Checkpoint Considerations 20 Opening and Closing GSAM Files 20 Program Area Management Considerations 21 Supported File Organizations 21 Application Error Processing SPICE Processing of Rollback Conditions 22 SPICE In-Flight Restart 23 Program Testing Initial Testing 24 Restart Testing 24 Chapter 3. Application Programming with SPICE DL/I SPICE DL/I Statements General Principles DL/I Statements using PCBs DL/I Statements using AIBs Language Support SPICE DL/I Programming Diagnostics Program Preparation SPICE DL/I Statement Layout Conventions Checkpoint & Restart Processing Restart Request (XRST Function Code) Description 31 Notes 32 Examples 33 Checkpoint Request (CHKP & CCHK Function Codes) Description 34 Notes 35 Examples 36 SPICE DL/I Rollback Request (ROLB Function Code) Description 37 Notes 38 Examples 38 In-Flight Restart Initialization Request (INIT Function Code) Description 38 Notes 39 Examples 39 Sequential File Processing SPICE DL/I GSAM PCBs & AIBs GSAM PCB Layout 40 AIB Support 41 iv SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

5 SPICE DL/I Processing of File DD Name 42 SPICE DL/I GSAM File Record Processing Record Length Processing 42 File Record Position Processing 42 GSAM File Open Request (OPEN Function Code) Description 43 Notes 43 Examples 43 GSAM File Sequential Read Request (GN Function Code) Description 44 Notes 44 Examples 45 GSAM File Reposition & Read Request (GU Function Code) Description 45 Examples 46 GSAM File Write Request (ISRT Function Code) Description 46 Notes 47 Examples 47 GSAM File Close Request (CLSE Function Code) Description 47 Examples 48 SPICE Services SPICE Program Testing Facility SPICE Test Request Description 50 Notes 50 Examples 51 SPICE DL/I Statement Parameter Summary Checkpoint & Restart Statements GSAM Sequential File Management Statements SPICE Services Statements Chapter 4. SPICE DL/I Application Administration Restart Database Administration IMS SPICE Restart Database Naming Rules IMS System Preparation IMS Restart Database Creation HDAM Restart Database Creation 57 DEDB Restart Database Creation 58 MSDB Restart Database Creation 59 IMS PSB Preparation IMS Restart Database Considerations SPICE Restart Database usage 60 Number of SPICE Restart Databases 60 SPICE Restart Database Security SPICE Restart Database Maintenance Deleting Inactive SPICE Restart Database Entries 61 SPICE MSDB Restart Database Repair 62 Application Program Administration Contents 18 June ,2009 Span Software Consultants Limited v

6 Application Program Compile and Link-Edit z/os Language Environment (LE) Considerations 64 Run Time Environments IMS Application PSB Preparation Sequential Dataset Allocation SPICE GSAM output files 66 Application Program JCL IMS BMP Execution of SPICE Application 67 IMS BMP Execution of SPICE SQL Application 67 IMS Batch Execution of SPICE Application 68 JCL Considerations 68 z/os Language Environment (LE) Considerations 69 Chapter 5. SPICE DL/I Operation Introduction to SPICE Operation Background SPICE TSO/ISPF Operator Subsystem SPICE Utility Program SPICE Operational Responsibilities Operations Personnel First Line Operations Personnel 73 Operations Support Personnel 73 Operations Planning Personnel 73 Development Personnel Database Administration and Technical Support Personnel Using the SPICE TSO/ISPF Operator Subsystem Getting Started A Brief Guide Database Table Processing Options 77 PSB Table Processing Options 78 Job Table Processing Options 78 Using the SPICE Utility Program SPICE Utility Program Execution IMS BMP Execution of SPICE Utility 79 IMS BMP Execution of SPICE Utility, attached to DB2 80 IMS Batch Execution of SPICE Utility 80 JCL Considerations 81 SPICE Utility Program Command Conventions SPICE Utility Program Help Command SPICE Restart Database Reports PSB Entry Reports SPICE Operator Subsystem 84 SPICE Utility Command 84 Formatted Report Contents 85 Dump Report Contents 86 Job Entry Reports SPICE Operator Subsystem 87 SPICE Utility Command 87 Formatted Report Contents 89 vi SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

7 Dump Report Contents 91 Default Values Entry Report SPICE Operator Subsystem 92 SPICE Utility Command 92 Formatted Report Contents 93 Dump Report Contents 94 MSDB Restart Database Contents Report SPICE Operator Subsystem 94 SPICE Utility Command 94 Report Contents 95 SPICE DL/I Application Program Execution Application PSB Registration SPICE Operator Subsystem 96 SPICE Utility Command 96 Application Program Start Determining Job Start Status 97 Application Program Restart Determining Job Restart Status 98 Application Program Rerun SPICE GSAM Dataset Recovery/Restart Physical Corruption 100 End of Extent/Volume Failure (e.g. B37 Abends) 100 Interrupting Application Program Execution SPICE Operator Subsystem 104 SPICE Utility Command 104 PSB Entry Report Specification 105 Controlling SPICE Features Default Value Processing SPICE Operator Subsystem 106 SPICE Utility Command 106 PSB Entry Report Specification 107 Checkpoint Suppression SPICE Operator Subsystem 108 SPICE Utility Command 108 PSB Entry Report Specification 109 Application Program Timeout SPICE Operator Subsystem 110 SPICE Utility Command 111 PSB Entry Report Specification 112 SPICE In-Flight Restart SPICE Operator Subsystem 114 SPICE Utility Command 114 PSB Entry Report Specification 115 SPICE Services Test Facility Checkpoint Braking SPICE Operator Subsystem 117 SPICE Utility Command 117 PSB Entry Report Specification 118 Application Program Termination SPICE Operator Subsystem 119 SPICE Utility Command 119 PSB Entry Report Specification 121 Contents 18 June ,2009 Span Software Consultants Limited vii

8 Other Facilities SPICE DL/I Restart Database Initialization SPICE Operator Subsystem 122 SPICE Utility Command 122 Disabling SPICE Restart SPICE Operator Subsystem 123 SPICE Utility Command 123 PSB Entry Report Specification 124 Restart Database Maintenance SPICE Operator Subsystem 124 SPICE Utility Command 125 SPICE MSDB Restart Database Repair SPICE Operator Subsystem 126 SPICE Utility Command 126 SPICE Operator Facilities Diagnostic Options SPICE Operator Subsystem 126 SPICE Utility Command 127 SPICE Utility Command Summary CHANGE Command DELETE Command HELP Command INIT Command LIST Command REPRO Command SET Command Appendix A. Migrating from Previous Versions Release Compatibility Database Compatibility DL/I Interface Routine Compatibility z/os Language Environment (LE) User Exit Deprecated SPICE Features FCHK Function Code SPICE SAM Pseudo-PCBs SPICE SAM Variable Length Record Support SPICE Operator Subsystem 132 SPICE Utility Command 133 PSB Entry Report Specification 133 SPICE Utility Commands TERM Function Code Discontinued SPICE Features Executing the SPICE Utility Program as an IMS Transaction Restart Under Different Jobname PSB Entry Report Specification 134 IMS Checkpointing using SYNC Function Code Glossary viii SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

9 Chapter 1. Introduction to SPICE DL/I Using This Manual This manual is the principal reference for SPICE DL/I. Chapter 1. Introduction to SPICE DL/I on page 1 This chapter is an introduction to the product. Chapter 2. SPICE DL/I Application Programming Principles on page 9 An introduction to the programming of SPICE DL/I restartable application programs. Chapter 3. Application Programming with SPICE DL/I on page 25 Information required to develop SPICE DL/I restartable application programs. Chapter 4. SPICE DL/I Application Administration on page 55 Information required to administer SPICE Restart Databases and application programs that use SPICE DL/I. Chapter 5. SPICE DL/I Operation on page 71 Information required to operate SPICE DL/I restartable application programs. Appendix A. Migrating from Previous Versions on page 131 Information that affects users of previous versions of the product. Introduction to SPICE DL/I 1 18 June ,2009 Span Software Consultants Limited

10 Introduction The explosion in the number of on-line application systems has not removed the need for batch processing. Every industry can quote processes that are most efficiently performed by programs that do not require direct supervision from a terminal. It is a growing trend that commercial and competitive considerations dictate that such processing be performed concurrently with the on-line systems. IMS applications can be run in such a fashion only if they are restartable. SPICE DL/I is a software package that complements the facilities of IBM's IMS system, for batch application programs. It provides a complete environment for the development, maintenance and operation of restartable IMS application programs. Users of SPICE DL/I benefit from the following: Operational benefits SPICE DL/I provides easy to use interactive facilities for controlling SPICE DL/I programs. It provides fully automatic restart of failing application programs, simply by re-submission of the job; no JCL changes are required. The same operational technique can be applied to all application jobs using SPICE DL/I. Development cost savings The SPICE DL/I programming facilities are simple to learn and use. SPICE DL/I programs request restart facilities, including sequential file processing, by issuing DL/I statements. Minimal training of programming staff is required. SPICE DL/I includes powerful facilities for controlling application program checkpoint processing. These facilities minimise the programmer's responsibility for checkpoint frequency. This results in less complex programs. SPICE DL/I also includes easy to use facilities for testing restartable application programs. Senior development staff are released from the task of developing and maintaining in-house facilities and procedures. SPICE DL/I results in reduced development and maintenance costs. Application integrity SPICE DL/I meets the highest standards of reliability and integrity. The nature and timing of external failures will not compromise the ability of SPICE DL/I to restart the application successfully. SPICE DL/I was developed and is marketed by Span Software Consultants Limited. Span Software has been providing software for IBM mainframes since Furthermore, Span Software has over 10 years of experience in delivering and maintaining software to support restartable applications. Span Software is proud of its record in providing and maintaining its software worldwide for z/os users in leading companies from all industry sectors. 2 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

11 R e s t a rtable Application Programs Many customers require that increasing numbers of their batch applications co-exist with their on-line applications. The mechanics of Data Base Management Systems require such application programs to be restartable. The reader will have experienced the frustration that occurs when one is interrupted from reading a book by a telephone call, only to discover upon return that the book has fallen shut. It can take some time to find again one's place in the story. A prudent reader makes intelligent use of a bookmark. In a similar way, restartable programs anticipate the possibility of system failure, and are so written as to minimize the difficulties that will arise when an interruption in processing occurs. Restartable programs regularly store information defining their current position in both program code and data, typically in databases. Following a failure, they use this data to minimize the processing that has to be repeated. The eventual state of the databases is unaffected by any interruptions that may occur. Programs that are not restartable have to process again from the beginning, which will often require the recovery of databases from backup copies. This can be a lengthy process. Selecting which backup copies to use can be a complex task, and may be prone to operator error. Furthermore, in the case of programs that update databases alongside the on-line systems, this form of recovery may result in the loss of database updates issued from on-line transactions. This recovery option may be unacceptable to business management, in which case batch applications will have to be restartable. Implementing restartable programs has previously lead to significant increases in costs, arising in both development and operational areas. SPICE DL/I and SPICE SQL have been conceived to minimize these additional costs. Introduction to SPICE DL/I 3 18 June ,2009 Span Software Consultants Limited

12 SPICE DL/I Summary on page 4 SPICE Program Area Management on page 4 SPICE Sequential File Management on page 5 SPICE Checkpoint Processing on page 5 SPICE Automatic Restart Processing on page 5 SPICE In-Flight Restart on page 5 SPICE Application Testing on page 6 SPICE Checkpoint Suppression on page 6 SPICE Application Timeout on page 6 Operating SPICE and its Application Programs on page 7 SPICE DL/I and SPICE SQL on page 7 S u m m ary SPICE DL/I is a software product that facilitates the implementation and operation of restartable IMS application programs. It enhances the standard facilities in IMS for restartable programs, providing significant improvements in application programming costs, operation reliability and ease of use. SPICE DL/I has its own IMS databases for managing its restartable application programs. SPICE DL/I has the follow ing characteristics: Application Program Interface Simple to use facilities, requested via standard interfaces. Minimal training requirements. Integration between IMS databases and OS sequential files. Operating Interface Simple to use facilities, available from a TSO/ISPF menu system. Minimal training requirements. Integration with automated operator facilities. Fail-safe operational procedures. SPICE Program Area Management SPICE program area management allows an application program to inform SPICE as to which of its data areas contain information that the program will require for successful restart. Should the application program fail, it will retrieve this information during restart processing, and restore the program's data areas to their contents at the time of the last checkpoint prior to the failure. 4 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

13 SPICE Sequential File Management SPICE DL/I includes facilities for the processing of sequential files. SPICE will maintain positioning information, in its database. Should the application program fail, SPICE will retrieve this information during restart processing, and automatically reposition each file to its position at the time of the last checkpoint prior to the failure. S P I C E Checkpoint Processing When SPICE decides to effect a checkpoint it performs the following: Saves the contents of designated application program data areas. Saves re-positioning information for sequential files under its control. Requests a checkpoint from IMS, to commit the updates to the databases. S P I C E Automatic Restart Processing SPICE automatically detects when an application program is restartable. The same set of JCL can be used for starting, restarting and rerunning SPICE applications, without change. When the program issues its restart request, SPICE will determine whether restart is required. When the program executes after a previous failure, SPICE will perform the following restart processing: Restore application program data areas upon application request. Re-position sequential files. SPICE facilities are available to override the program restart, so that the program may be rerun. S P I C E In-Flight Restart SPICE In-Flight Restart is an easy to use programming facility that can enable an application program to continue and complete its processing, despite conflicts with other application programs. If two programs compete for the same database entries the situation can arise where a deadlock occurs. When this happens the system will resolve the deadlock by discarding the uncommitted updates of one of them. In certain circumstances the affected application program is informed of this. An IMS PCB status code of BC, for instance, indicates that all uncommitted database updates have been lost. The application program can itself abandon uncommitted database updates by issuing an IMS ROLB statement. In either situation, the non-database files and the program areas are both out of step with the database contents. Without in-flight restart, the only sensible option available to an application program is that of immediate termination. SPICE In-Flight Restart allows the application program to continue and complete its processing without interruption. SPICE will detect the situations described above, and allow the application program to re-commence its processing from the previous Introduction to SPICE DL/I 5 18 June ,2009 Span Software Consultants Limited

14 checkpoint by re-issuing its restart request, thereby keeping databases, program areas and sequential files in synchronization. S P I C E Application Testing The SPICE application testing facility simplifies the testing of restartable application programs. It enables automated test suites to be developed that include thorough testing of application restart logic. Application programmers imbed breakpoints, coded as DL/I statements, within SPICE programs. These breakpoints are activated by special DD names in the program JCL. When these DD names are absent, SPICE will ignore the breakpoints. By altering the application JCL, the user can force the application to fail at the breakpoint. The user can then remove the JCL changes, so as to test restart of the program. S P I C E Checkpoint Suppression SPICE can reduce the load on a IMS system, by minimising the number of checkpoint requests processed by IMS. Furthermore, application design can be simplified, by reducing the sensitivity of the application to IMS checkpoint frequency. SPICE monitors the numbers of updated database segments and the time elapsed since the previous checkpoint. SPICE intercepts checkpoint requests. When appropriate, SPICE checkpoint processing can suppress unnecessary checkpoints, by returning control to the application, without committing the database updates. SPICE checkpoint suppression is fully under the control of the installation. The parameters are stored in a IMS database. They can easily be modified, by use of the SPICE operational interface, and require no modification to application program code or JCL. SPICE Application Timeout SPICE application timeout anticipates problems arising from excessive uncommitted database updates. It can terminate such ill-conditioned programs, before other applications are effected. SPICE monitors the number of database segments that have been updated since the previous database checkpoint. It also monitors the time interval over which database updates remain uncommitted. When appropriate, SPICE can intervene to control errant programs. SPICE application timeout is fully under the control of the installation. The parameters are stored in a IMS database. They can easily be modified, by use of the SPICE operational interface, and require no modification to application program code or JCL. 6 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

15 O p e r a ting SPICE and its Application Programs SPICE restartable application programs require little intervention from the operator. As SPICE restart requires no JCL change, most application and system failures require only that the program JCL be re-submitted. Control of the other SPICE facilities is performed with the easy to use SPICE TSO/ISPF operator subsystem. S P I C E DL/I and SPICE SQL SPICE SQL is a software product that facilitates the implementation and operation of restartable DB2 application programs. It extends DB2 to provide facilities appropriate to restartable programs, namely management of program data and sequential files required for restart, both synchronized with DB2 commit point processing. SPICE SQL has its own DB2 database for managing its restartable application programs. When both SPICE DL/I and SPICE SQL are installed, the following facilities are available in the IMS environment: i) SPICE will monitor both DL/I and SQL activity, and all its facilities will be available, in-flight restart for instance. ii) SPICE SQL programs may be run as BMPs; SPICE supports the SQL COMMIT and ROLLBACK statements from IMS BMPs. iii) SPICE application programs may use either IMS or DB2 databases as their SPICE Restart Database. Introduction to SPICE DL/I 7 18 June ,2009 Span Software Consultants Limited

16 8 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

17 Chapter 2. SPICE DL/I Application Programming Principles This chapter describes the facilities of SPICE DL/I that are available from application programs, and how programs should be coded to make use of them. It is divided into the following sections: SPICE DL/I Restartable Program Organization on page 10 This section discusses the need for restartable programs and their structure. SPICE DL/I Programming Facilities on page 15 This section serves as an introduction to SPICE DL/I Programming. It describes SPICE DL/I and its relationships with IMS, the principles underlying DL/I requests for SPICE DL/I facilities, and how SPICE DL/I responds to programming errors. Program Design Considerations on page 18 The effect that the SPICE DL/I facilities have upon the design of SPICE DL/I application programs is discussed in this section. SPICE DL/I Application Programming Principles 9 18 June ,2009 Span Software Consultants Limited

18 SPICE DL/I Restartable Program Organization This section explains the architecture of SPICE DL/I restartable programs. It illustrates the design of SPICE DL/I restartable programs with a simple program. Restartable Program Structure on page 10 Restartable Program Execution on page 13 R e s t a rtable Program Structure Simple Batch Program Consider the following Activity Diagram, which illustrates the structure of a typical batch program. Figure 2.1: Simple batch program It begins by performing its initialization, which will consist primarily of setting up its data in working storage. It might then position itself in its databases. It then proceeds to perform some form of repetitive processing until some criteria are met, when it terminates. It might, for instance, be processing data from a sequential file, in which case it would enter termination processing at end of file. If this program had to process and update large numbers of database segments, we might experience problems from the large number of uncommitted database entries that the program would hold. To overcome this problem we could decide to add some checkpoints. 10 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

19 Batch Program with Checkpoints Our program might then look like the following: Figure 2.2: Batch program with checkpoints Our program now issues checkpoints after processing each iteration of our processing loop. Because IMS, by default, loses database position during checkpoint processing, we have to reposition them after the checkpoint. Our program can now execute without holding large numbers of uncommitted updates. A problem might arise, however, should the program, or the system, fail during execution. Our program may have updated, and committed, many database entries. It may prove difficult, or even impossible, to determine which entries have been updated. The conventional strategy with such programs is to recover all the database tables to their state at the beginning of the job, before rerunning the program. This can be a lengthy and complex task. Furthermore, our databases might have been shared with other updating programs, the on-line network for instance. If so, the option to rerun may not be open to us; recovering our databases would undo all updates made by other programs. This may be unacceptable. We may then decide that our program should be restartable. SPICE DL/I Application Programming Principles June ,2009 Span Software Consultants Limited

20 Batch Program with SPICE DL/I If we use SPICE DL/I, our program would then look like the following: Figure 2.3: Restartable batch program We have determined those areas of the program required for restart, and issued DL/I statements to declare them to SPICE DL/I. We have also separated our initialization processing into two parts; that which is required once only, when the program first executes, and that required each time we execute, be it start or restart. Upon restart, we also skip the initial reposition of the databases and instead skip forward to the database reposition that we perform after each checkpoint. Our program is now restartable. 12 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

21 R e s t a rtable Program Execution We will now consider some execution scenarios, and walk through the processing that the program we developed in the previous topic will perform. Program Start We begin by performing general initialization. We then request restart and declare the program areas that we require for restart to SPICE DL/I. As this is the start of our processing, SPICE DL/I will hold no restart data for us and will respond with a checkpoint identifier of blanks. We will therefore have to initialize our restart data areas. Typical tasks performed here include obtaining the date, setting up database key variables, clearing totals, setting up check sums etc. This is a reasonable moment to issue a checkpoint. SPICE DL/I will now save the initial values of the restart data areas to its database. As we are not restarting, we will now position our databases before entering our main processing loop. At the end of each iteration of the program, we issue a checkpoint. SPICE DL/I will save the then current contents of the restart program areas to its restart database. At the end of each iteration of the program, we issue a checkpoint and reposition our databases. If our program runs to completion, SPICE DL/I will note the successful termination of the program. SPICE will return no restart data to a subsequent execution of the program. Program Restart We will suppose that a failure has occurred whilst our program was executing. Perhaps our program terminated abnormally. Alternatively z/os might have failed while we were running. We begin, as before, by performing general initialization. We then request restart and declare the program areas that we require for restart to SPICE DL/I. SPICE DL/I will recognise that this is a restart, and restore the restart data from the last successful checkpoint, to our restart program areas. It will return a non-blank checkpoint identifier. We must therefore skip that part of our program that performs restart data area initialization. This is again a reasonable moment to issue a checkpoint. SPICE DL/I will now save the current values of the restart data areas to its database. As we are restarting, we will now skip forward to reposition our databases before continuing our main processing loop. We will have included database reposition values in our restart data. The databases will therefore be positioned at the same point as that which would have been processed had the failure not occurred. Similarly other restart data, such as totals, check sums etc. will be unaffected by the failure. We can now continue processing, without the failure affecting the processing performed by our program. SPICE DL/I Application Programming Principles June ,2009 Span Software Consultants Limited

22 Program Rerun The failure may arise because of a severe program error that has been writing (and committing) incorrect updates to the application databases. Our databases may be in such a state that the only practical option is to rerun the program. To do this we will have to recover all application data to its state at the beginning of the program's execution. We also have to inform SPICE DL/I that rerun is required. These procedures are explained fully in Chapter 5. SPICE DL/I Operation on page 71. We can then start the program again. SPICE will not restore any restart data from its restart tables. 14 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

23 SPICE DL/I Programming Facilities This section describes the facilities that SPICE DL/I offers the application program. It also contains a discussion of the relationship between SPICE DL/I and various programming techniques and environments. Introduction to SPICE DL/I Programming Facilities on page 15 Program Area Management Facilities on page 15 Sequential File Processing Facilities on page 16 Application Testing Facilities on page 16 Checkpoint Facilities on page 17 Other Considerations on page 17 I n t r o d uction to SPICE DL/I Programming Facilities SPICE DL/I provides a comprehensive set of facilities for implementing restartable application programs. In particular, SPICE DL/I supports the management of program areas and sequential files. Application programs request SPICE facilities by issuing DL/I statements. As SPICE DL/I monitors all DL/I requests, it can recognise those statements that request SPICE facilities. P r o g r am Area Management Facilities Restartable programs define to SPICE the data areas that are required for successful restart of the program. SPICE saves the contents of these program areas in its database, for use during restart. Program areas are notified to SPICE by a DL/I statement, using the XRST function code. Up to seven areas may be defined to SPICE DL/I. The application program notifies SPICE of the data areas that should be saved for restart in each checkpoint request. Checkpoints are requested with a DL/I statement, using the DL/I function code CHKP. This statement indicates up to seven areas whose contents are to be saved to the SPICE Restart Database. When the program first executes, no data is restored in response to the XRST statement, and no checkpoint identifier is returned. When the program is restarted after a failure, SPICE DL/I restores the area contents as saved in the SPICE Restart Database, and returns the identifier of the checkpoint. SPICE DL/I Application Programming Principles June ,2009 Span Software Consultants Limited

24 S e q u e ntial File Processing Facilities SPICE DL/I provides facilities for the processing of sequential files via SPICE DL/I statements. The application program processes sequential files with SPICE DL/I by issuing DL/I statements against GSAM PCBs or AIBs. SPICE DL/I intercepts these statements and performs the appropriate processing. When the program first executes, file I/O will start from the beginning of the file. When the program restarts after a failure, SPICE DL/I repositions the file, so that file I/O will restart from the point of the last successful checkpoint. In other words, file processing will be unaffected by the interruption. Record Length Processing Programs that process records of variable or undefined length may determine the lengths of records read, and specify the lengths of those written. File Record Position Processing Programs are able to process file positions. They can save the current file position. At some later time, they can re-position the file to that point. A p p l i cation Testing Facilities SPICE DL/I includes a facility to assist in the testing of SPICE DL/I restartable programs, the SPICE services test facility. The facility enables economical automated testing procedures to be developed, that thoroughly exercise the restart logic of SPICE application programs. A SPICE Services test statement is imbedded at a point in the program where the programmer wishes to test a failure. The facility is controlled by DD statements in the application JCL. These JCL statements, typically assigned to DUMMY, define what action SPICE is to perform when the application issues a SPICE services test statement, abnormally terminate for instance. When the controlling DD statement is removed, the SQL statement will process successfully. It is thereby possible to design a suite of JCL that tests thoroughly the restart logic of a program. 16 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

25 C h e c kpoint Facilities Checkpoint Suppression SPICE checkpoint suppression is a technique that SPICE employs to control the frequency of application program IMS checkpoints. It can thereby reduce the load upon a IMS system. By diminishing the responsibility of application programs for checkpoint frequency, it can also simplify application design. An facility is available for the program to determine whether a checkpoint was suppressed. This allows the program to avoid unnecessary database re-positioning. Forced Checkpoint An application program can override SPICE checkpoint suppression, by issuing two checkpoint requests without any intervening processing. O t h e r Considerations SPICE DL/I and DB2 If the application programs are to issue DB2 SQL statements, the SPICE SQL product should be installed. SPICE DL/I and CICS SPICE facilities are appropriate only to batch processing, and therefore are not available, or meaningful, to CICS transactions. However, most application systems using CICS have ancillary processes performed by batch jobs. SPICE is eminently suited to these batch programs. SPICE DL/I Application Programming Principles June ,2009 Span Software Consultants Limited

26 Program Design Considerations Topics in this section discuss in more detail the facilities available to SPICE DL/I restartable programs, and what effect they might have on the design and structure of SPICE DL/I programs. Checkpoint Considerations on page 18 Restart Considerations on page 19 Sequential File Programming Considerations on page 20 Application Error Processing on page 22 Program Testing on page 24 C h e c kpoint Considerations This topic discusses design considerations for SPICE DL/I restartable programs that are associated with checkpoint processing. SPICE Checkpoint Suppression SPICE checkpoint suppression is a technique that SPICE employs to control the frequency of application program IMS checkpoints. It can thereby reduce the load upon a IMS system. By diminishing the responsibility of application programs for checkpoint frequency, it can also simplify application design. Further details of this feature may be found in topic Checkpoint Suppression on page 6. Location of Checkpoint statements DL/I checkpoint statements are best issued from key points in program logic, e.g. at the end of loops or when the program enters a new phase. This makes the program restart logic easier to understand, and write, than issuing checkpoints at fixed intervals in time, or after rigid counts of update statements. Checkpoint Frequency It is better for SPICE applications to issue too many checkpoints, than too few. It is suggested that application programs issue DL/I checkpoint statements at least every 100 database segment updates, or 10 elapsed seconds. Note that it is quite in order to issue checkpoint statements more frequently than this. SPICE checkpoint suppression will prevent a program's enthusiasm for checkpoints from overloading the IMS system. Forced Checkpoints An application program can override SPICE checkpoint suppression, and force a IMS checkpoint, by issuing two DL/I checkpoint statements without any intervening processing. Forced checkpoints are rarely necessary. An example of such is a program that is about to enter an extended period without issuing checkpoint requests (e.g. a long sort). It would be undesirable to leave any database updates uncommitted over the period of the processing. It would be appropriate to issue a double checkpoint here. 18 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

27 Post Checkpoint Processing SPICE DL/I application programs should always reposition their databases after issuing checkpoint requests with the CHKP function code. If they use the CCHK function code, they can test the i/o area to determine whether it is necessary to reposition the databases. R e s t a rt Considerations This topic discusses design considerations for SPICE DL/I restartable programs that are associated with the restart processing. Placement of XRST Statement The program areas declaration, using the XRST function code, should be placed very early in the program s processing. It will, typically, be the first DL/I statement in a program. Selecting Program Data for Restart What areas of the program should an application include in the areas that it declares to SPICE DL/I? It should include all data required to re-establish its processing upon program restart. Other than that, broadly speaking, as little as possible. All the restart data has to be written to the SPICE Restart Database; the more data, the more database and IMS log I/O activity. The following items of data should be considered: Data totals. Environment indicators, i.e. date and time of start of run. Check sums. Identification of which location in the program initiated the checkpoint. Database position key values. Sequential file buffers. Reasons why one might wish to consider checkpointing sequential file record area are discussed in topic Sequential File Programming Considerations, on page 20. SPICE DL/I Application Programming Principles June ,2009 Span Software Consultants Limited

28 S e q u e ntial File Programming Considerations This topic discusses those design considerations for SPICE DL/I restartable programs that are associated with the processing of sequential files. Record Length Processing The program may need to process record lengths for a file with variable length or undefined length records. Variable Length Records The binary record length is stored in a 2 byte prefix to the record. Undefined Length Records The length of undefined length records is communicated in a field in the PCB Restart Considerations When SPICE is restarted, sequential files that were open at the time of the last successful checkpoint will be re-positioned automatically. Checkpoint Considerations When SPICE DL/I takes a checkpoint, it saves the current positions of all the open GSAM files. Opening and Closing GSAM Files Programs that wish to explicitly open and/or close GSAM files, should always ensure that a checkpoint is taken, before performing any further action against the file. Topic Checkpoint Request (CHKP & CCHK Function Codes) on page 33 explains how this should be done. This is especially important when re-opening output files. This is performed typically to empty a file before writing out further records. The following example illustrates why. Consider the following processing scenario: 1) Write 1000 records to file OUTA. 2) Issue checkpoint. 3) Issue DL/I CLSE to request file close against OUTA. 4) Issue DL/I OPEN to request file open against OUTA. 5) Write 5 records to file OUTA. 6) Program or system failure. 7) Restart program, get failure when re-positioning OUTA. Upon restart, when the program attempts to write to OUTA, SPICE will attempt to reposition the file to the record following the last written before the restart checkpoint. The restart checkpoint is at point 2). The physical end of file however, will be after the records written at point 5). This will result in file failure. Forcing a checkpoint after point 3) avoids the restart failure. 20 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009

29 Program Area Management Considerations It is sometimes necessary to include the record buffer for a SPICE GSAM input file in the program areas required for restart. For example, consider an application that is driven by a file of transactions, stored in an sequential file. The transactions are processed in batches, relating to a particular key for example, before each checkpoint. The end of a batch is indicated by reading the first record from the following batch. This situation presents difficulties upon program restart. SPICE will reposition its files after the last record read. As the first record from the next batch has been read, the DL/I GN to the GSAM file PCB would retrieve the second record in the batch, thus causing the first to be missed. Three techniques are suggested for handling this situation. The transaction file could be designed to include a batch trailer record, to indicate positively the end of a batch. This technique is recommended when designing new systems. However, it may not be possible to change the design of an existing transaction file. Include the record buffer in the program's restart data areas. Thus, after restart from a successful checkpoint, the first record of the next batch is presented in the record buffer, without issuing a DL/L GN statement. Include the record search address (RSA) in the program's restart data areas. Each DL/I GN statement should request the optional RSA value. After restart from a successful checkpoint, the program can issue a GU, using the saved RSA, to reretrieve the record current at the time of the checkpoint. Supported File Organizations SPICE sequential file management supports the following file types, with full restart support; SPICE will automatically reposition files of these types when the program is restarted. z/os physical sequential datasets: any length record, fixed length, variable length and undefined length record formats. The program can access and specify the record length, if required. disk or tape, single or multiple volume. SPICE also processes the following file types, but without restart support. Upon restart; SPICE will not reset their position to that at the time of the restart checkpoint. When such files are used, SPICE will issue message SPI00112I to notify the user that restart repositioning is not available. JES input ( DD * ) and JES output ( SYSOUT ) files. TSO files ( DA(*) ). Concatenated input files. Members of partitioned data sets (PDS members). SPICE DL/I Application Programming Principles June ,2009 Span Software Consultants Limited

30 A p p l i cation Error Processing SPICE DL/I gives the maximum flexibility of options for application error processing, without compromising program restart. The following items summarize the related aspects of SPICE processing. SPICE Processing of Rollback Conditions SPICE recognises those PCB status codes that indicate that IMS was forced to abandon a program s uncommitted database updates, BC for instance. It also recognises explicit rollback statements, using the DL/I ROLB function code. These conditions result in loss of all database updates issued since the previous checkpoint. The state of the restart program areas and SPICE sequential files will not reflect the current contents of the databases. SPICE DL/I therefore suspends its processing of checkpoints until a restart has been performed. Following a rollback of database updates, SPICE allow s the program to perform any of the follow ing, w hilst retaining the restart data saved at the checkpoint preceding the rollback: Application database DL/I statements This allows the program to insert entries to an error database. DL/I checkpoint statements This allows the program to commit any updates issued after the rollback. SPICE will pass the DL/I checkpoint request on to IMS, but not alter the contents of its restart database. SPICE DL/I sequential file processing This allows the program to write error messages to SPICE GSAM files. DL/I rollback statements Unlikely, but the program can issue further DL/I ROLB statements, if it considers them appropriate. Normal termination This allows the program to terminate without an abend, yet restart upon re-submission. The pending restart is reactivated by one of the following actions: Program termination Restart request After termination of the program, SPICE will resume its standard processing: the next execution of the program will be processed as a restart. If the application program re-issues its XRST statement, SPICE will perform restart processing and restore the contents of the areas from its restart database tables. SPICE sequential files will also be re-positioned. This form of restart is termed SPICE inflight restart. As can be seen above, SPICE DL/I presents few obstacles to application error processing. SPICE DL/I does not prevent the program from updating its databases. As restart is suspended, the program could create a situation that conflicts with the data in the SPICE Restart Database tables. It is strongly recommended that enterprise data is not altered during error processing. Databases should be used only as a means of recording the error. 22 SPICE DL/I Product Reference Manual 1993,2008 Span Software Consultants Limited 18 June 2009