SPICE. SPICE DL/I Product Description. Release 1.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 Description Release 1.1 SPI Span Software Consultants Limited The Genesis Centre Birchwood Science Park WARRINGTON, CHESHIRE WA3 7BH UNITED KINGDOM Telephone +44 (0) Fax +44 (0) em ail spice@spansoftware.com website Copyright 1996, 2002 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. 1 October 2002

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 describes SPICE DL/I and its principal features. It is intended as an introduction to SPICE DL/I. Other SPICE Manuals SPI 08 SPICE SQL Product Reference Manual This manual is the principal reference for SPICE SQL, the SPICE product for the DB2 environment. SPI 09 SPICE DL/I Product Reference Manual This manual is the principal reference for SPICE DL/I, the SPICE product for the IMS 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 11 SPICE SQL Product Description This manual contains a brief description of SPICE SQL. SPI 13 SPICE SQL & SPICE DL/I Installation Manual 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, MVS, MVS/ESA and MVS/XA are trademarks of the International Business Machines Corporation. 2 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

3 Contents Chapter 1. Introduction to SPICE DL/I...5 Using This Manual 5 Introduction...6 Restartable Application Programs 7 SPICE DL/I...8 SPICE DL/I Facilities...9 SPICE DL/I Program Area Management 9 SPICE DL/I Sequential File Management 9 SPICE DL/I Checkpoint Processing 9 SPICE DL/I Automatic Restart Processing 9 SPICE DL/I In-Flight Restart 9 SPICE DL/I Application Testing 10 SPICE DL/I Checkpoint Suppression 10 SPICE DL/I Application Timeout 10 Operating SPICE DL/I and its Application Programs 11 SPICE DL/I and SPICE SQL 11 Chapter 2. Overview of SPICE DL/I Application Programming...12 SPICE DL/I Restartable Program Organization...13 Restartable Program Structure 13 Restartable Program Execution 14 SPICE DL/I Programming Fundamentals...16 The interface between SPICE DL/I and IMS 16 SPICE DL/I Programming Diagnostics 17 Other Considerations 17 Introduction to SPICE DL/I Programming Facilities...18 Program Area Management Facilities 18 Sequential File Processing Facilities 18 Checkpoint Facilities 20 Application Testing Facilities 22 Chapter 3. SPICE DL/I Operation...23 Introduction...24 Background 24 SPICE TSO/ISPF Operator Subsystem 24 SPICE Utility Program 24 SPICE DL/I Operational Responsibilities...25 Operations Personnel 25 Development Personnel 25 Database Administration and Technical Support Personnel 25 SPICE Restart Database Reports...26 PSB Entry Reports 26 Job Entry Reports 27 Default Values Entry Report 28 Chapter 4. SPICE DL/I Installation...29 Requirements 29 SPICE Installation 29 Glossary...30 Index...33 Contents 3 1 October , 2002 Span Software Consultants Limited

4 Figures Figure 2.1: Structure of simple batch program 13 Figure 2.2: Structure of batch program with checkpoints 13 Figure 2.3: Structure of restartable batch program 14 COBOL Example 2.1: Restart Statement 18 COBOL E xample 2.2: Read record from input file 19 COBOL E xample 2.3: Write record to output file 19 COBOL Example 2.4: Checkpoint processing using function code CHKP 20 COBOL Example 2.5: Checkpoint processing using function code CCHK 21 COBOL Example 2.6: Forced checkpoint processing, using double checkpoint 21 COBOL Example 2.7: Request the SPICE services test facility 22 Report Example 3.1: Formatted Report of PSB Entry 26 Report Example 3.2: Formatted Report of Job Entry 27 Report Example 3.3: Formatted Report of Default Values entry 28 4 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

5 Chapter 1. Introduction to SPICE DL/I Using This Manual This manual is a guide to the function and facilities of SPICE DL/I. This chapter is an introduction to the product. Read this chapter for a brief overview of SPICE DL/I and its facilities. Chapter 2, Overview of SPICE DL/I Application Programming, introduces the architecture of SPICE DL/I restartable programs, and contains an overview of how SPICE DL/I facilities are requested from an application program. Chapter 3, SPICE DL/I Operation, is a summary of the operational responsibilities that SPICE DL/I restartable programs require. Chapter 4, SPICE DL/I Installation, discusses the software requirements of SPICE DL/I. Introduction to SPICE DL/I 5 1 October , 2002 Span Software Consultants Limited

6 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 resubmission 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 MVS users in leading companies from all industry sectors. 6 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

7 Restartable 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 7 1 October , 2002 Span Software Consultants Limited

8 SPICE DL/I 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 following 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. 8 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

9 SPICE DL/I Facilities SPICE DL/I Program Area Management SPICE DL/I program area management allows an application program to inform SPICE DL/I 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. SPICE DL/I Sequential File Management SPICE DL/I includes facilities for the processing of sequential files. SPICE DL/I will maintain positioning information, in its database. Should the application program fail, SPICE DL/I 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. SPICE DL/I Checkpoint Processing When SPICE DL/I 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. SPICE DL/I Automatic Restart Processing SPICE DL/I automatically detects when an application program is restartable. The same set of JCL can be used for starting, restarting and rerunning SPICE DL/I applications, without change. When the program issues its restart request, SPICE DL/I will determine if restart is required. When the program executes after a previous failure, SPICE DL/I will perform the following restart processing:! Restore application program data areas upon application request.! Re-position sequential files. SPICE DL/I facilities are available to override the program restart, so that the program may be rerun. SPICE DL/I In-Flight Restart SPICE DL/I 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 Introduction to SPICE DL/I 9 1 October , 2002 Span Software Consultants Limited

10 database contents. Without in-flight restart, the only sensible option available to an application program is that of immediate termination. SPICE DL/I in-flight restart allows the application program to continue and complete its processing without interruption. SPICE DL/I will detect the situations described above, and allow the application program to re-commence its processing from the previous checkpoint by re-issuing its restart request, thereby keeping databases, program areas and sequential files in synchronization. SPICE DL/I Application Testing The SPICE DL/I 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 DL/I 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. SPICE DL/I Checkpoint Suppression SPICE DL/I 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 DL/I monitors the numbers of updated database segments and the time elapsed, since the previous checkpoint. SPICE intercepts checkpoint requests. When appropriate, SPICE DL/I checkpoint processing can suppress unnecessary checkpoints, by returning control to the application, without committing the database updates. SPICE DL/I 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 DL/I operational interface, and require no modification to application program code or JCL. SPICE DL/I Application Timeout SPICE DL/I application timeout anticipates problems arising from excessive uncommitted database updates. It can terminate such ill-conditioned programs, before other applications are impacted. SPICE DL/I 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 DL/I 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 DL/I operational interface, and require no modification to application program code or JCL. 10 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

11 Operating SPICE DL/I and its Application Programs SPICE DL/I restartable application programs require little intervention from the operator. As SPICE DL/I 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. SPICE 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, without change, in the DB2 environment; 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 11 1 October , 2002 Span Software Consultants Limited

12 Chapter 2. Overview of SPICE DL/I Application Programming This chapter introduces the architecture of SPICE DL/I restartable programs, and contains an overview of how SPICE DL/I facilities are requested from an application program. It is divided into the following sections: SPICE DL/I Restartable Program Organization (page 13). In this section, we discuss the need for restartable programs and their structure. SPICE DL/I Programming Fundamentals (page 16). 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. Introduction to SPICE DL/I Programming Facilities (page 18). This section introduces the facilities available to SPICE DL/I programs. 12 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

13 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. It does not initially take into account SPICE sequential files or SPICE checkpoint suppression. The reader is then walked through the processes of start, restart and rerun. Restartable Program Structure Simple Batch Program Consider the following figure. It illustrates the structure of a typical batch program Processing: Initialization Position data bases < Repetitive Processing End of processing? (no) -- Termination Figure 2.1: Structure of 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. Batch Program with Checkpoints Our program might then look like the following: Processing: Initialization Position data bases < Repetitive Processing Issue checkpoint Reposition data bases End of processing? (no)- Termination Figure 2.2: Structure of batch program with checkpoints Overview of SPICE DL/I Application Programming 13 1 October , 2002 Span Software Consultants Limited

14 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. Batch Program with SPICE DL/I If we use SPICE DL/I, our program would then look like the following: Processing: Initialization (non-restart) Issue restart for program areas Restart? (yes) Prime restart areas < Issue checkpoint Restart? (yes) Position data bases < Repetitive Processing Issue checkpoint < Reposition data bases End of processing? (no)-- Termination Figure 2.3: Structure of 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. Restartable 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, 14 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

15 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 MVS 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. 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. We can then start the program again. SPICE will not restore any restart data from its restart tables. Overview of SPICE DL/I Application Programming 15 1 October , 2002 Span Software Consultants Limited

16 SPICE DL/I Programming Fundamentals This section describes the fundamental principles of programming with SPICE DL/I. It details the requirements of application programs that wish to use SPICE DL/I facilities. The general requirements of DL/I statements that request SPICE DL/I facilities are described. Finally, the section contains a discussion of the relationship between SPICE DL/I and various programming techniques and environments. The interface between SPICE DL/I and IMS General Principles 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 against IMS PCBs or AIBs. SPICE DL/I can recognise these statements, and will perform the requested function directly; they are not passed on to IMS. SPICE DL/I can detect these requests because it intercepts all DL/I statements issued by the application program. DL/I statements concerned with checkpoint processing, notably XRST, CHKP and ROLB, initiate additional processing by SPICE DL/I. DL/I statements issued against GSAM PCBs or AIBs are processed directly by SPICE DL/I. The requested operation upon the associated sequential file is performed by SPICE DL/I. SPICE DL/I then returns control to the application program. When errors are detected in the processing of GSAM PCBs or AIBs, SPICE DL/I returns the appropriate PCB status code. DL/I statements issued against application databases are passed promptly on to IMS for processing. SPICE DL/I monitors database updates, and PCB status codes returned by IMS. PCB status codes indicating serious problems, notably deadlock conditions, can initiate further SPICE DL/I processing. Otherwise, SPICE DL/I performs no additional processing. Language Support SPICE DL/I will execute with all programming languages supported by IMS. Program Preparation For SPICE DL/I application programs the IMS high level language interface routine (DFSLI000) is replaced by the SPICE HLI routine (SPIDHLI0). The application is linkedited to include the SPICE DL/I interface. The SPICE DL/I HLI should also be included in all separately linked modules that the program references. SPICE DL/I is thereby able to process all DL/I statements before IMS. A PCB for the SPICE restart database must be included in the application PSB. This PCB may be hidden from the application PCB list, by defining the PCB as LIST=NO. If the SPICE SQL product is installed, the application can use the SPICE SQL database tables, as its restart database. 16 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

17 SPICE DL/I Programming Diagnostics When SPICE DL/I detects an error, it inserts a message into the MVS job log. It then returns to the program, placing an appropriate value in the status code field of the request PCB. The values of the status code conform to those used by IMS. Upon detecting an error indicator, most application programs enter their standard error handling code, possibly resulting in abnormal termination of the program. Other 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. Overview of SPICE DL/I Application Programming 17 1 October , 2002 Span Software Consultants Limited

18 Introduction to SPICE DL/I Programming Facilities This section contains an overview of the facilities available to SPICE DL/I application programs. Program Area Management Facilities Restartable programs define to SPICE DL/I 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. The following COBOL example illustrates how an area of program storage is declared to SPICE DL/I as necessary for the restart of the program. 01 FUNC-XRST PIC X(04) VALUE 'XRST'. 01 MAX-PATH-LEN PIC 9(09) COMP VALUE IOAREA. 02 CHKP-ID PIC X(08). 02 FIELD-1 PIC 9(09) COMP. 02 FIELD-2 PIC X(68). 01 AREA-1-LEN PIC 9(09) COMP VALUE AREA-1 PIC X(32) VALUE SPACES. 01 AREA-2-LEN PIC 9(09) COMP VALUE AREA FIELD-1 PIC X(16) VALUE SPACES. LINKAGE SECTION. 01 IO-PCB i/o pcb layout PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB,... CALL 'CBLTDLI' USING FUNC-XRST, IO-PCB, MAX-PATH-LEN, IOAREA, AREA-1-LEN, AREA-1, AREA-2-LEN, AREA-2. COBOL Example 2.1: Restart Statement The example declares field AREA-1 and structure AREA-2 to SPICE DL/I as areas of program storage necessary for the restart of the program. When the program first executes, no data is restored in response to the XRST statement, and no value is returned in checkpoint identifier field CHKP-ID. 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 in field CHKP-ID. Sequential 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. SPICE DL/I will reposition the files automatically 18 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

19 upon restart. At restart, SPICE DL/I will synchronize its sequential files with the application database contents. Input File Processing Input files are processed using the DL/I function codes GN and GU. If required, a file may explicitly be opened or closed with the DL/I function codes OPEN and CLSE. The following example illustrates how records may be read from SPICE GSAM files using the DL/I function code GN. 01 FUNC-GN PIC X(04) VALUE 'GN '. 01 REC-IN-AREA. 02 FIELD-1 PIC X(16) VALUE SPACES. LINKAGE SECTION. 01 GSAM-PCB. 02 GSAM-DBD PIC X(08) gsam pcb layout PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB,..., GSAM-PCB. CALL 'CBLTDLI' USING FUNC-GN, GSAM-PCB, REC-IN-AREA. COBOL Example 2.2: Read record from input file Records from the file defined in the GSAM DBD named in PCB GSAM-PCB are read into I/O area REC-IN-AREA. SPICE DL/I returns a PCB status code of blanks when each record is successfully read. The value GB is returned when end of file is reached in the file. When the program first executes, file I/O will begin with the first record in the file. When the program is restarted after a failure, SPICE DL/I will reposition the file. File I/O will restart from the point of the last successful checkpoint. In other words, file processing will be unaffected by the interruption. Output File Processing Output files are processed using the DL/I function code ISRT. If required, a file may explicitly be opened or closed with the DL/I function codes OPEN and CLSE. The following COBOL example illustrates how records may be written to SPICE GSAM files. 01 FUNC-ISRT PIC X(04) VALUE 'ISRT'. 01 REC-OUT-AREA. 02 FIELD-1 PIC X(16) VALUE SPACES. LINKAGE SECTION. 01 GSAM-PCB. 02 GSAM-DBD PIC X(08) gsam pcb layout PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB,..., GSAM-PCB. CALL 'CBLTDLI' USING FUNC-ISRT, GSAM-PCB, REC-OUT-AREA. COBOL Example 2.3: Write record to output file Records from I/O area REC-OUT-AREA are written to the file defined in the GSAM DBD named in the PCB GSAM-PCB. SPICE DL/I returns a PCB status code of blanks when each record is successfully processed. When the program first executes, file I/O will begin at the beginning of the file. When the program is restarted after a failure, SPICE DL/I will reposition the file. 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. Overview of SPICE DL/I Application Programming 19 1 October , 2002 Span Software Consultants Limited

20 File Record Position Processing Programs may request that SPICE DL/I returns a value representing the current file position. It can also request, using the GU function code, re-position of the file to a point defined by such a value. Checkpoint 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. The following COBOL example illustrates checkpoint processing in SPICE DL/I, using the CHKP function code. 01 FUNC-CHKP PIC X(04) VALUE 'CHKP'. 01 MAX-PATH-LEN PIC 9(09) COMP VALUE IOAREA. 02 CHKP-ID PIC X(08). 02 FIELD-1 PIC 9(09) COMP. 02 FIELD-2 PIC X(68). 01 AREA-1-LEN PIC 9(09) COMP VALUE AREA-1 PIC X(32) VALUE SPACES. 01 AREA-2-LEN PIC 9(09) COMP VALUE AREA FIELD-1 PIC X(16) VALUE SPACES. LINKAGE SECTION. 01 IO-PCB i/o pcb layout PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB,... CALL 'CBLTDLI' USING FUNC-CHKP, IO-PCB, MAX-PATH-LEN, IOAREA, AREA-1-LEN, AREA-1, AREA-2-LEN, AREA-2. COBOL Example 2.4: Checkpoint processing using function code CHKP After the DL/I CHKP statement the resultant status code should be examined. Failures excepted, it will always take the value of blanks. As the program is unaware of suppressed checkpoints, it should assume that database position has been lost, and reposition its databases before proceeding. For most programs this is entirely satisfactory. It is possible, however, that the overhead of redundant database re-positioning becomes unacceptable. To cater for this situation, SPICE DL/I introduces the CCHK function code. 20 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

21 The following COBOL example illustrates checkpoint processing in SPICE DL/I, using the CCHK function code. 01 FUNC-CCHK PIC X(04) VALUE 'CCHK'. 01 MAX-PATH-LEN PIC 9(09) COMP VALUE IOAREA. 02 CHKP-ID PIC X(08). 02 FIELD-1 PIC 9(09) COMP. 02 FIELD-2 PIC X(68). 01 AREA-1-LEN PIC 9(09) COMP VALUE AREA-1 PIC X(32) VALUE SPACES. 01 AREA-2-LEN PIC 9(09) COMP VALUE AREA FIELD-1 PIC X(16) VALUE SPACES. LINKAGE SECTION. 01 IO-PCB i/o pcb layout PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB,... CALL 'CBLTDLI' USING FUNC-CCHK, IO-PCB, MAX-PATH-LEN, IOAREA, AREA-1-LEN, AREA-1, AREA-2-LEN, AREA-2. COBOL Example 2.5: Checkpoint processing using function code CCHK After the DL/I CCHK statement the resultant i/o area should be examined. Field FIELD-1 of IOAREA will take the value of either 0 or 4. The value 0 indicates that a IMS checkpoint occurred, in which case the program should reposition the databases. The value 4 indicates that SPICE DL/I suppressed the checkpoint, in which case the databases retain their position. Forced Checkpoint An application program can override SPICE checkpoint suppression, by issuing two DL/I CHKP statements without any intervening processing. The following COBOL example illustrates forced checkpoint processing in SPICE DL/I. 01 FUNC-CHKP PIC X(04) VALUE 'CHKP'. 01 MAX-PATH-LEN PIC 9(09) COMP VALUE IOAREA. 02 CHKP-ID PIC X(08). 02 FIELD-1 PIC 9(09) COMP. 02 FIELD-2 PIC X(68). 01 AREA-1-LEN PIC 9(09) COMP VALUE AREA-1 PIC X(32) VALUE SPACES. 01 AREA-2-LEN PIC 9(09) COMP VALUE AREA FIELD-1 PIC X(16) VALUE SPACES. LINKAGE SECTION. 01 IO-PCB i/o pcb layout PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB,... CALL 'CBLTDLI' USING FUNC-CHKP, IO-PCB, MAX-PATH-LEN, IOAREA, AREA-1-LEN, AREA-1, AREA-2-LEN, AREA-2. CALL 'CBLTDLI' USING FUNC-CHKP, IO-PCB, MAX-PATH-LEN, IOAREA, AREA-1-LEN, AREA-1, AREA-2-LEN, AREA-2. COBOL Example 2.6: Forced checkpoint processing, using double checkpoint After the DL/I CHKP statements the program must reposition any databases it is processing. Overview of SPICE DL/I Application Programming 21 1 October , 2002 Span Software Consultants Limited

22 Application 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 DL/I 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. The application program requests the SPICE services test facility by issuing DL/I statements to the I/O PCB using the TEST function code. SPICE DL/I intercepts these statements and performs the appropriate processing. The following example illustrates the facility: 01 FUNC-TEST PIC X(04) VALUE 'TEST'. 01 TEST-PREFIX PIC X(05) VALUE 'TESTS'. LINKAGE SECTION. 01 IO-PCB i/o pcb layout PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB,... CALL 'CBLTDLI' USING FUNC-TEST, IO-PCB, TEST-PREFIX. COBOL Example 2.7: Request the SPICE services test facility When the statement is executed, SPICE DL/I will respond according to the DD names allocated to the job step. If DD name TESTSDIE is found, SPICE will abnormally terminate the program. If DD name TESTSERR is found, SPICE will return an I/O PCB status code of ZZ to the program, which will typically then perform standard error processing. If, however, neither DD name is found, SPICE will return to the application, placing a status code of blanks in the I/O PCB. 22 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

23 Chapter 3. SPICE DL/I Operation This chapter is a summary of the operational responsibilities that SPICE DL/I restartable programs require. It is divided into the following sections: Introduction (page 24). This section describes the facilities available in SPICE for controlling SPICE DL/I and its applications. SPICE DL/I Operational Responsibilities (page 25). This section discusses the responsibilities of the installation's staff towards the SPICE operator facilities. SPICE Restart Database Reports (page 26). This section describes how reports on the contents of the SPICE restart database may be obtained, and explains the information they contain. SPICE DL/I Operation 23 1 October , 2002 Span Software Consultants Limited

24 Introduction This section serves as an introduction to the facilities of SPICE DL/I that are used for the operational control of SPICE DL/I and its applications. Topics covered include the use of the operator facilities by installation staff. Background SPICE is designed specifically to minimize the involvement of operations staff in the day to day running of restartable SPICE DL/I programs. For instance, application program restart requires the operator only to resubmit the job JCL, without modification. Most installations have, as an objective, the adoption of standard operating procedures across application systems. Reducing the variety and complexity of application operation can both increase system reliability, and reduce operating costs. SPICE DL/I can contribute significantly to this objective, as the same simple procedures can be utilized for all application systems that use it. With the exception of application program restart, SPICE DL/I applications are administered either with the SPICE TSO/ISPF operator subsystem or the SPICE utility program. Both provide easy to use facilities that allow the user to report upon and administer applications. SPICE TSO/ISPF Operator Subsystem The SPICE operator subsystem is a set of interactive panels and programs that provide an easy to use interface to SPICE. They allow operational personnel to administer SPICE and its applications in an intuitive manner from a TSO terminal, through the use of the subsystem's menus and extensive help and tutorial panels. SPICE Utility Program The SPICE utility program is a batch program. It can be used by operational personnel to administer SPICE and its applications. Commands are read from the program's input stream and processed accordingly. Printed reports may be obtained on the contents of a SPICE restart database. 24 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

25 SPICE DL/I Operational Responsibilities This section summarizes the uses to which the SPICE operator facilities can be put by various categories of installation personnel. Operations Personnel First Line Operations Personnel Staff responsible for the day to day operation of SPICE DL/I applications can use the facilities of SPICE for the following:! To monitor the state of applications, by using the SPICE reporting options.! To restart SPICE DL/I jobs, following system or program failure, by re-submitting the JCL. Operations Support Personnel Staff responsible for resolving problems in the day to day operation of SPICE DL/I applications can use the facilities of SPICE for the following:! To determine the state of applications, by using the SPICE reporting options.! To indicate that the application program is to be rerun, rather than restarted. This decision may require consultation with development staff. Use of this facility can be expected to be infrequent. Operations Planning Personnel Staff responsible for planning the implementation of applications that use SPICE DL/I can use the facilities of SPICE for the following:! To register new application programs in the SPICE restart database.! To control which SPICE facilities are to be used. Development Personnel Staff responsible for developing SPICE DL/I applications can use the facilities of SPICE for the following:! To monitor the state of their application programs, by using the SPICE reporting options.! To control which SPICE facilities are to be used, according to the current testing requirements of a program.! Following application program failure, to restart their jobs or indicate that the application program is to be rerun. Database Administration and Technical Support Personnel Staff responsible for the technical aspects of SPICE DL/I applications can use the facilities of SPICE for the following:! To create and initialize the SPICE restart database.! To decide which SPICE DL/I facilities should be used, and select suitable parameter values for them. The implementation of these decisions might be performed by operations planning personnel. SPICE DL/I Operation 25 1 October , 2002 Span Software Consultants Limited

26 SPICE Restart Database Reports This section describes the reports on the contents of the SPICE restart database that can be obtained from the SPICE operator facilities. They are obtained with the LIST option (SPICE operator subsystem) or LIST command (SPICE utility). The SPICE restart database contains the following entry types: PSB Entries Job Entries Default Values Entry Define the SPICE options that are to be used when the named PSB is executed with SPICE. Contain, for executing restartable SPICE programs, the information necessary for successful program restart. The data may be spread over more than one entry in the database table. There can be sets of entries for any number of different job names for a PSB entry. Defines certain SPICE options that are to be used for PSBs that are designated as using these default values. PSB Entry Reports The following example is an instance of a formatted report of a PSB entry. PSB SPIVP4CP entry created :54:15.0 last change :40:34.7 restart entry length 2030 Commit Point Suppression (DEFAULT VALUES) thresholds: seconds updates DB2 & IMS BMP regions IMS BATCH regions Application Timeout (DEFAULT VALUES) WTO upon application timeout thresholds: seconds updates DB2 & IMS BMP regions IMS BATCH regions 0 0 Commit Point Braking (DEFAULT VALUES) wait period: seconds DB2 & IMS BMP regions 0 IMS BATCH regions 0 Report Example 3.1: Formatted Report of PSB Entry PSB entry created, last change restart entry length Commit Point Suppression Application Timeout Commit Point Braking The name of the application program. The date and time when the entry was created and last altered by SPICE operator facilities. Length of job entry segment. Values of SPICE checkpoint suppression parameters. The values labelled DB2 & IMS BMP regions apply when the PSB is run as a BMP. The values labelled IMS BATCH regions apply when the PSB is run as batch IMS. Values of SPICE application timeout parameters. The values labelled DB2 & IMS BMP regions apply when the PSB is run as a BMP. The values labelled IMS BATCH regions apply when the PSB is run as batch IMS. Values of SPICE checkpoint braking parameters. The values labelled DB2 & IMS BMP regions apply when the PSB is run as a BMP. The values labelled IMS BATCH regions apply when the PSB is run as batch IMS. Other Indicators (when present) (DEFAULT VALUES) Indicates that the parameters used to control this feature are taken from the default values entry in the database. Absence 26 SPICE DL/I Product Description 1993, 2002 Span Software Consultants Limited 1 October 2002

27 of this text indicates that SPICE will take its parameters from the PSB entry. Job Entry Reports The following example is an instance of a formatted report of a job entry. PSB SPIVP4CP JOB SPICEJOB SPICEJOB step PROCPURC program SPIVP4CP entry created :43:58.2 last change :38:49.7 last start :20:50.0 last restart :00:00.0 last stop :22:21.3 last commit :20:50.3 identifier SPI00001 since last Statistics: since job start start/restart commit points issued by program 7 7 commit points issued to DBMS 1 1 number database entries updated 11 seconds elapsed 2 Report Example 3.2: Formatted Report of Job Entry JOB, step, program entry created, last change last start, last restart, last finish last commit identifier commit points... program commit points... DBMS number... entries updated seconds elapsed The name of the job, the name of the step in its JCL and the program name. The date and time when the entry was created and last altered by SPICE operator facilities. The date and time when this execution of the program started, was last restarted and completed. Note: last restart can be zero, indicating that the job has not been restarted since this execution started. Note: last finish can precede last start This indicates that this execution of the program has not yet reached completion; it is either running or has abnormally terminated. The time and date when the program last issued a checkpoint. Identifier assigned to the checkpoint by the program. The number of checkpoints that the program has issued since last start and since the latest of last start and last restart. The number of checkpoints that SPICE has passed on to IMS since last start and since the latest of last start and last restart. These values will never be higher those of the preceding line in the report. Note: The two columns only differ after a failure of the program has resulted in a restart, in which case the values in the first column will be higher. The number of database entries that have been updated by the program since the latest of last start and last restart. The time for which the program has been executing, in seconds, since the latest of last start and last restart. Other Indicators (when present) ACTIVE This text, when present, indicates that the specified job is executing, or has failed and restart is required. SPICE will perform restart processing when the job is next executed. Absence of this text indicates that SPICE will perform normal start processing when the job is next executed. SPICE DL/I Operation 27 1 October , 2002 Span Software Consultants Limited