SPICE DL/I Product Reference Manual
Transcription
SPICE DL/I Product Reference Manual
Span SPICE In t e g r a t e d Ch e c kp o in t / Re s t a r t En v i r o n me n t SPICE DL/I™ Product Reference Manual Release 3.1 SPI 09 14 Span Software Consultants Limited Little Moss, Peacock Lane High Legh Knutsford Cheshire WA16 6P L UNIT ED KINGDOM T elephone: Fax: email website +44 (0) 1565 832999 +44 (0) 1565 830653 spice@spansoftware.com httl://www.spansoftware.com © Copyright 1993, 2009 Span Software Consultants Limited. All rights reserved. No part of this publication may be re-produced, store d in a r etrieval 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 Preface Abstract SPICE is an acronym for Span Integrated Checkpoint/Restart Environment. SPICE DL/I™ is a softw are 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 Softw are 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 Contents Chapter 1. Introduction to SPICE DL/I™. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Using This Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Restartable Application Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 SPICE DL/I. . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . SPICE Program Area Management. . . . . . . . . . SPICE Sequential File Management. . . . . . . . . . SPICE Checkpoint Processing. . . . . . . . . . . . . SPICE Automatic Restart Processing. . . . . . . . SPICE In-Flight Restart™. . . . . . . . . . . . . . . . SPICE Application Testing. . . . . . . . . . . . . . . . SPICE Checkpoint Suppression. . . . . . . . . . . . SPICE Application Timeout. . . . . . . . . . . . . . . Operating SPICE and its Application Programs. . SPICE DL/I and SPICE SQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4 4 5 5 5 5 6 6 6 7 7 Chapter 2. SPICE DL/I™ Application Programming Principles. . . . . . . . . . . . . . . . 9 SPICE DL/I Restartable Program Organization. . . . . . . . . . . . . . . . . . . . . . . . 10 Restartable Program Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Simple Batch Program 10 Batch Program w ith Checkpoints 11 Batch Program w ith SPICE DL/I 12 Restartable Program Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 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 File Record Position Processing Application Testing Facilities. . . . . . . . . . . . . . . . . Checkpoint Facilities. . . . . . . . . . . . . . . . . . . . . . . Checkpoint Suppression Forced Checkpoint Other Considerations. . . . . . . . . . . . . . . . . . . . . . . SPICE DL/I and DB2 SPICE DL/I and CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 15 15 16 16 16 . . . . . . . . . . . . . . . . . . . . 16 . . . . . . . . . . . . . . . . . . . . 17 17 17 . . . . . . . . . . . . . . . . . . . . 17 17 17 Program Design Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Checkpoint Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 SPICE Checkpoint Suppression 18 Cont ent s 18 June 2009 © 1993,2009 Span Software Consultants Limited iii Location of Checkpoint statements Checkpoint Frequency Forced Checkpoints Post Checkpoint Processing Restart Considerations. . . . . . . . . . . . . . . . . . Placement of XRST Statement Selecting Program Data for Restart Sequential File Programming Considerations. . . Record Length Processing Restart Considerations Checkpoint Considerations Opening and Closing GSAM Files Program Area Management Considerations Supported File Organizations Application Error Processing. . . . . . . . . . . . . . SPICE Processing of Rollback Conditions SPICE In-Flight Restart™ Program Testing. . . . . . . . . . . . . . . . . . . . . . Initial Testing Restart Testing ....................... ....................... ....................... ....................... 18 18 18 19 19 19 19 20 20 20 20 20 21 21 22 22 23 24 24 24 Chapter 3. Application Programming with SPICE DL/I™. . . . . . . . . . . . . . . . . . . 25 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Check point & Restart Processing. . . . . . . . . . . . . . . . . . . . . Restart Request (XRST Function Code). . . . . . . . . . . . . . . . Description Notes Examples Checkpoint Request (CHKP & CCHK Function Codes). . . . . Description Notes Examples SPICE DL/I Rollback Request (ROLB Function Code). . . . . . Description Notes Examples In-Flight Restart Initialization Request (INIT Function Code). Description Notes Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 26 27 28 29 29 29 30 . . . . . . . . . . . . . 31 . . . . . . . . . . . . . 31 31 32 33 . . . . . . . . . . . . . 33 34 35 36 . . . . . . . . . . . . . 37 37 38 38 . . . . . . . . . . . . . 38 38 39 39 Sequential File Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 SPICE DL/I GSAM PCBs & AIBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 GSAM PCB Layout 40 AIB Support 41 iv SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE DL/I Processing of File DD Name SPICE DL/I GSAM File Record Processing. . . . . . . . . . . . . . Record Length Processing File Record Position Processing GSAM File Open Request (OPEN Function Code). . . . . . . . . Description Notes Examples GSAM File Sequential Read Request (GN Function Code). . . . Description Notes Examples GSAM File Reposition & Read Request (GU Function Code). . Description Examples GSAM File Write Request (ISRT Function Code). . . . . . . . . . Description Notes Examples GSAM File Close Request (CLSE Function Code). . . . . . . . . Description Examples 42 . . . . . . . . . . . . . 42 42 42 . . . . . . . . . . . . . 43 43 43 43 . . . . . . . . . . . . . 44 44 44 45 . . . . . . . . . . . . . 45 45 46 . . . . . . . . . . . . . 46 46 47 47 . . . . . . . . . . . . . 47 47 48 SPICE Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 SPICE Program Testing Facility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 SPICE Test Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Description 50 Notes 50 Examples 51 SPICE DL/I Statement Parameter Summary. . . Checkpoint & Restart Statements. . . . . . . . . . . GSAM Sequential File Management Statements. SPICE Services Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 52 53 53 Chapter 4. SPICE DL/I™ Application Administration. . . . . . . . . . . . . . . . . . . . . . 55 Restart Database Administration. . . . . . . . . . . . . . . . IMS SPICE Restart Database Naming Rules. . . . . . . IMS System Preparation. . . . . . . . . . . . . . . . . . . . . IMS Restart Database Creation. . . . . . . . . . . . . . . . . HDAM Restart Database Creation DEDB Restart Database Creation MSDB Restart Database Creation IMS PSB Preparation. . . . . . . . . . . . . . . . . . . . . . . IMS Restart Database Considerations. . . . . . . . . . . . SPICE Restart Database usage Number of SPICE Restart Databases SPICE Restart Database Security. . . . . . . . . . . . . . . SPICE Restart Database Maintenance. . . . . . . . . . . . Deleting Inactive SPICE Restart Database Entries SPICE MSDB Restart Database Repair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ................... ................... ................... ................... 55 55 56 56 57 58 59 59 60 60 60 61 61 61 62 Application Program Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Cont ent s 18 June 2009 © 1993,2009 Span Software Consultants Limited v Application Program Compile and Link-Edit. . . . . . . . z/OS Language Environment (LE) Considerations Run Time Environments. . . . . . . . . . . . . . . . . . . . . . IMS Application PSB Preparation.. . . . . . . . . . . . . . . Sequential Dataset Allocation. . . . . . . . . . . . . . . . . . . SPICE GSAM output files Application Program JCL. . . . . . . . . . . . . . . . . . . . . IMS BMP Execution of SPICE Application IMS BMP Execution of SPICE SQL Application IMS Batch Execution of SPICE Application JCL Considerations z/OS Language Environment (LE) Considerations . . . . . . . . . . . . . . . . . . 63 64 . . . . . . . . . . . . . . . . . . 65 . . . . . . . . . . . . . . . . . . 65 . . . . . . . . . . . . . . . . . . 66 66 . . . . . . . . . . . . . . . . . . 67 67 67 68 68 69 Chapter 5. SPICE DL/I™ Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Introduction to SPICE Operation . . . . . . Background.. . . . . . . . . . . . . . . . . . . . SPICE TSO/ISPF Operator Subsystem. SPICE Utility Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SPICE Operational Responsibilities. . . . . . . . . . Operations Personnel. . . . . . . . . . . . . . . . . . . First Line Operations Personnel Operations Support Personnel Operations Planning Personnel Development Personnel. . . . . . . . . . . . . . . . . Database Administration and Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 71 72 72 . . . . . . . . . . . . . . . . . . . . . . . 73 . . . . . . . . . . . . . . . . . . . . . . . 73 73 73 73 . . . . . . . . . . . . . . . . . . . . . . . 74 Personnel. . . . . . . . . . . . . . . . 74 Using the SPICE TSO/ISPF Operator Subsystem. . . . . . . . . . . . . . . . . . . . . . . 75 Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 A Brief Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 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 IMS BMP Execution of SPICE Utility, attached to DB2 IMS Batch Execution of SPICE Utility JCL Considerations SPICE Utility Program Command Conventions. . . . . . . . . . SPICE Utility Program Help Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 . . . . . . . . . . . . . . 79 79 80 80 81 . . . . . . . . . . . . . . 81 . . . . . . . . . . . . . . 82 SPICE Restart Database Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 PSB Entry Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 SPICE Operator Subsystem 84 SPICE Utility Command 84 Formatted Report Contents 85 Dump Report Contents 86 Job Entry Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 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 Dump Report Contents 91 Default Values Entry Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 SPICE Operator Subsystem 92 SPICE Utility Command 92 Formatted Report Contents 93 Dump Report Contents 94 MSDB Restart Database Contents Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 SPICE Operator Subsystem 94 SPICE Utility Command 94 Report Contents 95 SPICE DL/I Application Program Execution. . . . . . . . Application PSB Registration. . . . . . . . . . . . . . . . . . SPICE Operator Subsystem SPICE Utility Command Application Program Start. . . . . . . . . . . . . . . . . . . . Determining Job Start Status Application Program Restart.. . . . . . . . . . . . . . . . . . Determining Job Restart Status Application Program Rerun. . . . . . . . . . . . . . . . . . . SPICE GSAM Dataset Recovery/Restart. . . . . . . . . . Physical Corruption End of Extent/Volume Failure (e.g. B37 Abends) Interrupting Application Program Execution. . . . . . . . SPICE Operator Subsystem SPICE Utility Command PSB Entry Report Specification Controlling SPICE Features. . . . . . . . Default Value Processing. . . . . . . . . SPICE Operator Subsystem SPICE Utility Command PSB Entry Report Specification Checkpoint Suppression. . . . . . . . . SPICE Operator Subsystem SPICE Utility Command PSB Entry Report Specification Application Program Timeout. . . . . . SPICE Operator Subsystem SPICE Utility Command PSB Entry Report Specification SPICE In-Flight Restart ™.. . . . . . . SPICE Operator Subsystem SPICE Utility Command PSB Entry Report Specification SPICE Services Test Facility. . . . . . Checkpoint Braking. . . . . . . . . . . . . SPICE Operator Subsystem SPICE Utility Command PSB Entry Report Specification Application Program Termination. . . SPICE Operator Subsystem SPICE Utility Command PSB Entry Report Specification . . . . . . . . . . . . . . . . . . . 96 . . . . . . . . . . . . . . . . . . . 96 96 96 . . . . . . . . . . . . . . . . . . . 97 97 . . . . . . . . . . . . . . . . . . . 97 98 . . . . . . . . . . . . . . . . . . . 99 . . . . . . . . . . . . . . . . . . 100 100 100 . . . . . . . . . . . . . . . . . . 104 104 104 105 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 106 106 107 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 108 108 109 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 110 111 112 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 114 114 115 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 117 117 118 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 119 119 121 Cont ent s 18 June 2009 © 1993,2009 Span Software Consultants Limited vii Other Facilities. . . . . . . . . . . . . . . . . . . . . . . . SPICE DL/I Restart Database Initialization. . . SPICE Operator Subsystem SPICE Utility Command Disabling SPICE Restart. . . . . . . . . . . . . . . . SPICE Operator Subsystem SPICE Utility Command PSB Entry Report Specification Restart Database Maintenance. . . . . . . . . . . . SPICE Operator Subsystem SPICE Utility Command SPICE MSDB Restart Database Repair. . . . . . SPICE Operator Subsystem SPICE Utility Command SPICE Operator Facilities Diagnostic Options. SPICE Operator Subsystem SPICE Utility Command . . . . . . . . . . . . . . . . . . . . . . . . 122 . . . . . . . . . . . . . . . . . . . . . . . . 122 122 122 . . . . . . . . . . . . . . . . . . . . . . . . 123 123 123 124 . . . . . . . . . . . . . . . . . . . . . . . . 124 124 125 . . . . . . . . . . . . . . . . . . . . . . . . 125 126 126 . . . . . . . . . . . . . . . . . . . . . . . . 126 126 127 SPICE Utility Command Summary. CHANGE Command. . . . . . . . . . DELETE Command. . . . . . . . . . . HELP Command. . . . . . . . . . . . . INIT Command. . . . . . . . . . . . . . LIST Command.. . . . . . . . . . . . . REPRO Command. . . . . . . . . . . . SET Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 128 129 129 130 130 130 130 Appendix A. Migrating from Previous Versions.. . . . . . . . . . . . . . . . . . . . . . . . . . 131 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 SPICE Utility Command PSB Entry Report Specification SPICE Utility Commands. . . . . . . . . . . . . . . TERM Function Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 . 131 . 131 . 131 . 132 . 132 . 132 . 132 132 133 133 . . . . . . . . . . . . . . . . . . . . . . . . 133 . . . . . . . . . . . . . . . . . . . . . . . . 134 Discontinued SPICE Features. . . . . . . . . . . . . . . . . . . . . . . . Executing the SPICE Utility Program as an IMS Transaction. Restart Under Different Jobname. . . . . . . . . . . . . . . . . . . . . PSB Entry Report Specification IMS Checkpointing using SYNC Function Code. . . . . . . . . . . . . . . . . . . . . . . 134 . . . . . . . . . . . . . 134 . . . . . . . . . . . . . 134 134 . . . . . . . . . . . . . 135 Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 viii SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 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 t o SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 1 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 grow ing 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 softw are 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 follow ing: • 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 pow erful 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 w ill not compromise the ability of SPICE DL/I to restart the application successfully. SPICE DL/I w as developed and is marketed by Span Softw are Consultants Limited. Span Softw are has been providing software for IBM mainframes since 1976. Furthermore, Span Softw are has over 10 years of experience in delivering and maintaining softw are to support restartable applications. Span Softw are is proud of its record in providing and maintaining its softw are w orldw ide 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 Restartable Application Programs Many customers require that increasing numbers of their batch applications co-exist w ith their on-line applications. The mechanics of Data Base Management Systems require such application programs to be restartable. The reader w ill have experienced the frustration that occurs w hen 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 w ay, restartable programs anticipate the possibility of system failure, and are so w ritten as to minimize the difficulties that w ill arise w hen an interruption in processing occurs. Restartable programs regularly store information defining their current position in both program code and data, typically in databases. Follow ing 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, w hich w ill often require the recovery of databases from backup copies. This can be a lengthy process. Selecting w hich 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 w hich case batch applications w ill 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 t o SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 3 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 Summary SPICE DL/I is a softw are 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 ow n 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 betw een IMS databases and OS sequential files. Operating Interface • • • • Simple to use facilities, available from a TSO/ISPF menu system. Minimal training requirements. Integration w ith automated operator facilities. Fail-safe operational procedures. SPICE Program Area Management SPICE program area management allows an application program to inform SPICE as to w hich of its data areas contain information that the program w ill 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 SPICE Sequential File Management SPICE DL/I includes facilities for the processing of sequential files. SPICE w ill maintain positioning information, in its database. Should the application program fail, SPICE w ill 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 Checkpoint Processing When SPICE decides to effect a checkpoint it performs the follow ing: • 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 Automatic Restart Processing SPICE automatically detects w hen an application program is restartable. The same set of JCL can be used for starting, restarting and rerunning SPICE applications, w ithout change. When the program issues its restart request, SPICE w ill determine whether restart is required. When the program executes after a previous failure, SPICE w ill perform the follow ing 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. SPICE 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 w ith other application programs. If tw o programs compete for the same database entries the situation can arise where a deadlock occurs. When this happens the system w ill 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 w ith 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 allow s the application program to continue and complete its processing w ithout interruption. SPICE w ill detect the situations described above, and allow the application program to re-commence its processing from the previous Introduction t o SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 5 checkpoint by re-issuing its restart request, thereby keeping databases, program areas and sequential files in synchronization. SPICE 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, w ithin SPICE programs. These breakpoints are activated by special DD names in the program JCL. When these DD names are absent, SPICE w ill 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 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, w ithout 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 w hich 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 Operating 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 w ith the easy to use SPICE TSO/ISPF operator subsystem. SPICE DL/I and SPICE SQL SPICE SQL™ is a softw are 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 w ith DB2 commit point processing. SPICE SQL has its ow n DB2 database for managing its restartable application programs. When both SPICE DL/I and SPICE SQL are installed, the follow ing facilities are available in the IMS environment: i) SPICE w ill monitor both DL/I and SQL activity, and all its facilities w ill 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 t o SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 7 8 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 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 follow ing 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 w ith 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 18 June 2009 © 1993,2009 Span Software Consultants Limited 9 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 w ith a simple program. Restartable Program Structure on page 10 Restartable Program Execution on page 13 Restartable Program Structure Simple Batch Program Consider the follow ing Activity Diagram, w hich illustrates the structure of a typical batch program. Figure 2.1: Simple batch program It begins by performing its initialization, which w ill consist primarily of setting up its data in w orking storage. It might then position itself in its databases. It then proceeds to perform some form of repetitive processing until some criteria are met, w hen it terminates. It might, for instance, be processing data from a sequential file, in w hich case it w ould enter termination processing at end of file. If this program had to process and update large numbers of database segments, w e 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 Batch Program with Check points Our program might then look like the follow ing: Figure 2.2: Batch program w ith 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 w ithout holding large numbers of uncommitted updates. A problem might arise, how ever, 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 w hich entries have been updated. The conventional strategy w ith 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 w ith other updating programs, the on-line network for instance. If so, the option to rerun may not be open to us; recovering our databases w ould 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 18 June 2009 © 1993,2009 Span Software Consultants Limited 11 Batch Program with SPICE DL/I If w e use SPICE DL/I, our program w ould then look like the follow ing: 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 tw o parts; that w hich is required once only, w hen 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 forw ard to the database reposition that w e 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 Restartable Program Execution We will now consider some execution scenarios, and w alk 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 w ill hold no restart data for us and will respond w ith a checkpoint identifier of blanks. We w ill 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 w e are not restarting, w e w ill now position our databases before entering our main processing loop. At the end of each iteration of the program, w e issue a checkpoint. SPICE DL/I w ill save the then current contents of the restart program areas to its restart database. At the end of each iteration of the program, w e issue a checkpoint and reposition our databases. If our program runs to completion, SPICE DL/I w ill note the successful termination of the program. SPICE w ill return no restart data to a subsequent execution of the program. Program Restart We w ill suppose that a failure has occurred w hilst our program w as executing. Perhaps our program terminated abnormally. Alternatively z/OS might have failed w hile w e w ere running. We begin, as before, by performing general initialization. We then request restart and declare the program areas that w e require for restart to SPICE DL/I. SPICE DL/I w ill recognise that this is a restart, and restore the restart data from the last successful checkpoint, to our restart program areas. It w ill 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 w e are restarting, w e w ill now skip forw ard 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 w hich w ould have been processed had the failure not occurred. Similarly other restart data, such as totals, check sums etc. w ill 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 18 June 2009 © 1993,2009 Span Software Consultants Limited 13 Program Rerun The failure may arise because of a severe program error that has been w riting (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 w e 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 w ill 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 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 betw een 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 Introduction 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. Program 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 w ith a DL/I statement, using the DL/I function code CHKP. This statement indicates up to seven areas w hose 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 18 June 2009 © 1993,2009 Span Software Consultants Limited 15 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 w ith 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 w ill 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 w ill restart from the point of the last successful checkpoint. In other w ords, file processing w ill 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 w ritten. 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. 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 Services test statement is imbedded at a point in the program w here the programmer w ishes to test a failure. The facility is controlled by DD statements in the application JCL. These JCL statements, typically assigned to DUMMY , define w hat action SPICE is to perform w hen the application issues a SPICE services test statement, abnormally terminate for instance. When the controlling DD statement is removed, the SQL statement w ill 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 Checkpoint Facilities Check point 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 w as suppressed. This allow s the program to avoid unnecessary database re-positioning. Forced Check point An application program can override SPICE checkpoint suppression, by issuing two checkpoint requests w ithout any intervening processing. 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. How ever, 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 18 June 2009 © 1993,2009 Span Software Consultants Limited 17 Program Design Considerations Topics in this section discuss in more detail the facilities available to SPICE DL/I restartable programs, and w hat 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 Checkpoint Considerations This topic discusses design considerations for SPICE DL/I restartable programs that are associated w ith checkpoint processing. SPICE Check point 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 Check point 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 w rite, than issuing checkpoints at fixed intervals in time, or after rigid counts of update statements. Check point 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 w ill prevent a program's enthusiasm for checkpoints from overloading the IMS system. Forced Check points An application program can override SPICE checkpoint suppression, and force a IMS checkpoint, by issuing two DL/I checkpoint statements w ithout any intervening processing. Forced checkpoints are rarely necessary. An example of such is a program that is about to enter an extended period w ithout issuing checkpoint requests (e.g. a long sort). It w ould be undesirable to leave any database updates uncommitted over the period of the processing. It w ould be appropriate to issue a double checkpoint here. 18 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Post Check point Processing SPICE DL/I application programs should alw ays reposition their databases after issuing checkpoint requests w ith the CHKP function code. If they use the CCHK function code, they can test the i/o area to determine w hether it is necessary to reposition the databases. Restart Considerations This topic discusses design considerations for SPICE DL/I restartable programs that are associated w ith 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 w ritten to the SPICE Restart Database; the more data, the more database and IMS log I/O activity. The follow ing items of data should be considered: • Data totals. • Environment indicators, i.e. date and time of start of run. • Check sums. • Identification of w hich location in the program initiated the checkpoint. • Database position key values. • Sequential file buffers. • Reasons w hy 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 18 June 2009 © 1993,2009 Span Software Consultants Limited 19 Sequential File Programming Considerations This topic discusses those design considerations for SPICE DL/I restartable programs that are associated w ith the processing of sequential files. Record Length Processing The program may need to process record lengths for a file w ith 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. Check point 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 w ish to explicitly open and/or close GSAM files, should alw ays 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 w riting out further records. The follow ing example illustrates w hy. Consider the follow ing processing scenario: 1) 2) 3) 4) 5) 6) 7) Write 1000 records to file OUTA . Issue checkpoint. Issue DL/I CLSE to request file close against OUTA . Issue DL/I OPEN to request file open against OUTA . Write 5 records to file OUTA . Program or system failure. Restart program, get failure w hen re-positioning OUTA . Upon restart, w hen the program attempts to write to OUTA , SPICE w ill attempt to reposition the file to the record follow ing the last w ritten before the restart checkpoint. The restart checkpoint is at point 2). The physical end of file how ever, w ill be after the records written at point 5). This w ill 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 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 follow ing batch. This situation presents difficulties upon program restart. SPICE w ill 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 w ould 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 w hen designing new systems. How ever, 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, w ithout 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 follow ing file types, w ith full restart support; SPICE w ill automatically reposition files of these types w hen 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 follow ing file types, but without restart support. Upon restart; SPICE w ill not reset their position to that at the time of the restart checkpoint. When such files are used, SPICE w ill 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 18 June 2009 © 1993,2009 Span Software Consultants Limited 21 Application Error Processing SPICE DL/I gives the maximum flexibility of options for application error processing, w ithout compromising program restart. The follow ing items summarize the related aspects of SPICE processing. SPICE Processing of Rollback Conditions SPICE recognises those PCB status codes that indicate that IMS w as 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 w ill not reflect the current contents of the databases. SPICE DL/I therefore suspends its processing of checkpoints until a restart has been performed. Follow ing 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: This allow s 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 w ill pass the DL/I checkpoint request on to IMS, but not alter the contents of its restart database. S PICE DL/I sequential file processing This allow s the program to w rite 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 allow s the program to terminate w ithout an abend, yet restart upon re-submission. Application database DL/I statements The pending restart is reactivated by one of the follow ing actions: Program termination Restart request After termination of the program, SPICE w ill 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 w ill perform restart processing and restore the contents of the areas from its restart database tables. SPICE sequential files w ill 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 w ith 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 SPICE In-Flight Restart™ As noted in the previous item, SPICE DL/I includes a facility for performing restart w hilst the program is executing: SPICE in-flight restart. A program may thereby avoid an operator initiated restart. SPICE DL/I permits in-flight restart only after the rolling back of a program's database updates. This situation can arise in one of tw o w ays. Firstly, the program can deliberately cause it to happen, by issuing a DL/I rollback request, using the ROLB function code. Secondly, it can be invoked by IMS in response to a detected error situation. When IMS detects a database segment deadlock betw een two programs, for instance, it is able to dynamically roll back the database updates of one of them, before returning it a PCB status code of “BC”. Follow ing the rolling back of uncommitted updates, the application program can regain synchronization betw een the databases, program areas and SPICE GSAM files by reissuing its XRST statement. This will recover the contents of the program's program areas, to their state at the restart checkpoint. The SPICE GSAM files w ill be automatically re-positioned to that point. Use of SPICE In-Flight Restart requires that the program do the follow ing: • If the program w ishes to receive “BC” status codes w hen deadlock occurs, it should issue a DL/I statement to the I/O PCB using function code INIT, w ith value “STATUS GROUPB” in the I/O area. Programs that use IMS fast path databases receive automatically the backout status codes indicating backout, “FD“ etc. • Monitor PCB status codes for values that indicate rollback, i.e.“BC”, “FA ”, “FD”, “FR”, “FS” and “FV ”. • Issue DL/I rollback, using the function code ROLB, during error processing for other conditions for w hich it wishes to attempt in-flight restart. • To initiate the restart it is suggested that the program branch back to the code preceding the restart statement. Thus the processing w ould be identical to that which w ould have been performed had the program terminated abnormally and then been restarted. SPICE w ill limit the number of consecutive in-flight restarts, w ithout an intervening checkpoint. Should the limit be exceeded, SPICE w ill issue message SPI0118I and Abend. SPICE DL/I thereby prevents an irresolvable deadlock from suspending the program indefinitely. This limit is stored in the SPICE Restart Database, and may be altered. See SPICE In-Flight Restart ™ on page 113 for further details. SPICE DL/I™ Application Programming Principles 18 June 2009 © 1993,2009 Span Software Consultants Limited 23 Program Testing It is, of course, essential that the code relating to the restart of an application program be executed, as part of the development test plan. This topic w ill discuss how the testing of a program can be simplified, by the use of SPICE facilities. Initial Testing Most programmers find that SPICE automatic restart is a hindrance in the early stages of testing. Imagine that a failure has occurred in one area of a program's logic. The programmer finds the bug and corrects it, and then executes the program again. SPICE w ill attempt to restart the program. It is quite possible that there is a further fault in the restart logic of the program. Thus our programmer ends up having to debug two areas of the program at the same time. It is possible to sw itch off SPICE restart, as described in topic Disabling SPICE Restart on page 123. It is recommended that SPICE restart is disabled until the program executes reliably. SPICE DL/I may then be enabled, so that its ability to restart successfully may be tested. Restart Testing To test restart processing of a restartable application, it is necessary first to generate a failure in its execution. The program must then be executed w ithout the failure. The simplest technique is to cancel the program and then resubmit it. This may require the cooperation of the operator, and w ould not select the point of failure precisely. SPICE DL/I includes the SPICE DL/I services test facility to aid the controlled testing of the restart logic of a program. It is first necessary to decide at w hich point the program should fail; just before a checkpoint is a good choice. The action that SPICE DL/I w ill perform is dependent upon w hich DD names are present in the job JCL. The follow ing DD statements may be included in the JCL to request the related action, w here prefix is the value of the DD name prefix specified in the test facility request: //prefixDIE DD DUMMY //prefixERR DD DUMMY The program w ill abnormally terminate. The program w ill receive an error diagnostic. This option is useful for testing the error processing logic of the program. To test the program, it should first be executed w ith one of the above DD names present. The program job can then be rerun w ith the DD statement omitted, w hen it should restart and run successfully to completion. 24 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Chapter 3. Application Programming with SPICE DL/I™ This chapter describes how application programs can use SPICE DL/I to request SPICE DL/I facilities. • • • • • SPICE DL/I Statements on page 26 Checkpoint & Restart Processing on page 31 Sequential File Processing on page 40 SPICE Services on page 49 SPICE DL/I Statement Parameter Summary on page 52 SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 25 SPICE DL/I Statements This section describes the follow ing aspects of SPICE DL/I: • • • • • • • General Principles on page 26 DL/I Statements using PCBs on page 27 DL/I Statements using AIBs on page 28 Language Support on page 29 SPICE DL/I Programming Diagnostics on page 29 Program Preparation on page 29 SPICE DL/I Statement Layout Conventions on page 30 General Principles Application programs request SPICE facilities by issuing DL/I statements. SPICE DL/I monitors all DL/I requests, and recognises those statements that request SPICE facilities. DL/I statements concerned w ith 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. It performs the requested operation upon the associated sequential file. DL/I statements issued against application databases are passed directly 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. Otherw ise, SPICE DL/I performs no processing. When SPICE DL/I detects errors in the processing of application requests, SPICE DL/I returns an appropriate PCB status code. Whenever meaningful, SPICE DL/I passes PCB status codes returned by IMS back to the application. 26 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 DL/I Statements using PCBs COBOL CALL 'CBLTDLI' USING function, pcb, i/o area [,ssa1,...,ssa15]. CALL PLITDLI (parmcount, function, pcb, i/o area [,ssa1,...,ssa15]); PL/I Pascal PASTDLI(CONST function, VAR pcb, VAR i/o area [, VAR ssa1, ... VAR ssa15]); C #pragma runopts(env(IMS),plist(IMS)) #include <ims.h> int rc; rc = ctdli(&function, &pcb, &i/o area [,&ssa1,...,&ssa15]); Assem bler Language CALL ASMTDLI,(function,pcb, X i/o area[,ssa1,...,ssa15]),VL DL/I Diagram 3.1: DL/I statement using PCB Description parmcount The name of an area in your program that contains a 4 byte integer value of the number of parameters that follow. This parameter is only required for PL/I DL/I statements. function The name of an area in your program that contains the 4 byte function code. pcb The name of the area in your program that contains the program communication block (PCB). i/o area The name of the I/O area in your program. ssa... The names of up to 15 areas in your program, containing segment search areas (SSAs). SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 27 DL/I Statements using AIBs COBOL CALL 'AIBTDLI' USING function, aib, i/o area [,ssa1,...,ssa15]. CALL AIBTDLI (parmcount, function, aib, i/o area [,ssa1,...,ssa15]); PL/I Pascal AIBTDLI(CONST function, VAR aib, VAR i/o area [, VAR ssa1, ... VAR ssa15]); C #pragma runopts(env(IMS),plist(IMS)) #include <ims.h> int rc; rc = aibtdli(&function, &aib, &i/o area [,&ssa1,...,&ssa15]); Assem bler Language CALL AIBTDLI,(function,aib, X i/o area[,ssa1,...,ssa15]),VL DL/I Diagram 3.2: DL/I statement using AIB Description parmcount The name of an area in your program that contains a 4 byte integer value of the number of parameters that follow . This parameter is only required for PL/I DL/I statements. function The name of an area in your program that contains the 4 byte function code. aib The name of the area in your program that contains the application interface block (AIB). You are responsible for initialising the AIB w ith the name of the PCB that you wish to process. For complete information on DL/I processing using AIBs, you are referred to the IMS documentation. i/o area The name of the I/O area in your program. ssa... The names of up to 15 areas in your program, containing segment search areas (SSAs). 28 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Language Support SPICE DL/I can be used w ithin programs of any language that request IMS facilities through the *TDLI functions. SPICE DL/I Programming Diagnostics When SPICE DL/I detects an error, it inserts a message into the z/OS 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. Program Preparation SPICE DL/I application programs require the follow ing: 1) The IMS high level language interface routine (DFSLI000) must be replaced by the SPICE HLI routine (SPIDHLI0). The application is link-edited 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. 2) SPICE DL/I must have access to a SPICE Restart Database. The follow ing options are supported: • 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 a SPICE DB2 Restart Database. This is requested by including a DD statement assigned to name SPIOFDB2 in the JCL. Alternatively, it can be requested by including a PCB in the PSB for a database, w hose DBD name begins w ith the characters SPICR. Find further information on the preparation of SPICE programs in Chapter 4. SPICE DL/I™ Application Administration on page 55. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 29 SPICE DL/I Statement Layout Conventions For the remainder of the manual, DL/I statement parameter list contents w ill be documented via railroad diagrams. For instance, here is the parameter list for the DL/I restart statement. >>--- XRST ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+ >-------------.------------------------------------.------------------>< | | | .----------------------------. | | | | | | v | | +---.--- area length --- area ---.---+ DL/I Diagram 3.3: DL/I Parameter List Example Read this as representing a parameter list of elements: • XRST • One of the follow ing alternatives: • i/o pcb • i/o aib • i/o area len • i/o area • A number of occurrences of pairs of: • area length • area Follow ing each diagram w ill be a description of w hat each element represents. 30 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Checkpoint & Restart Processing This section describes the follow ing aspects of SPICE DL/I: • • • • Restart Request (XRST Function Code) on page 31 Checkpoint Request (CHKP & CCHK Function Codes) on page 33 SPICE DL/I Rollback Request (ROLB Function Code) on page 37 In-Flight Restart Initialization Request (INIT Function Code) on page 38 Restart Request (XRST Function Code) SPICE DL/I programs define themselves as restartable w ith the DL/I restart statement. The statement also declares those program areas w hose contents are required for program restart. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- XRST ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+ >-------------.------------------------------------.------------------>< | | | .----------------------------. | | | | | | v | | +---.--- area length --- area ---.---+ DL/I Diagram 3.4: SPICE DL/I restart statement (XRST ) Description XRST The name of an area in your program that contains the 4 byte function code “XRST”. i/o pcb The name of the area in your program that contains the I/O PCB, the first PCB in the PCB list. i/o aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the character value “IOPCB ”. The routine name “AIBTDLI” must be used. i/o area len The name of an area in your program that contains the 4 byte binary length of the longest segment, or path of segments, in your program. i/o area The name of the I/O area in your program. It must be at least 8 bytes long. The first 8 bytes should be set to blanks. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 31 area len The name of an area in your program that contains the 4 byte binary length of the follow ing area parameter. area The name of an area in your program, w hose contents are required for restart. You may specify up to 7 program restart areas. Their number and lengths must be such that any of the program's checkpoint statements can be restored, w ithout any data left over. Notes Upon a restart statement, SPICE DL/I examines its restart database. If it holds data for the PSB and job name from a previous checkpoint, it will restart the program. If no such data is found, the program w ill start normally. For a normal start, SPICE DL/I w ill set the contents of the I/O area to blanks and not change the contents of the program restart areas. It will not alter the positions of the GSAM files. For a restart, SPICE DL/I w ill store the restart checkpoint identifier in the first 8 bytes of the I/O area and restore the contents of the designated program restart areas. It will position GSAM files to w here they w ere at the time of the restart checkpoint. It also restores the contents of the database PCB key feedback areas from the checkpoint. The restart statement should be issued early in the execution of the program, before any checkpoint statements are issued. Any prior DL/I statements are outside the scope of the restart. The restart statement can be re-issued, when IMS has abandoned the program's uncommitted database updates, follow ing a status code of “BC” or ROLB statement, for instance. Further information may be found in topic SPICE In-Flight Restart™ on page 5. 32 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Examples 01 FUNC-XRST 01 MAX-PATH-LEN 01 IOAREA. 02 CHKP-ID 02 FIELD-1 02 FIELD-2 01 AREA-1-LEN 01 AREA-1 01 AREA-2-LEN 01 AREA-2. 02 FIELD-1 PIC X(04) PIC 9(09) PIC PIC PIC PIC PIC PIC VALUE 'XRST'. COMP VALUE 128. X(08). 9(09) X(68). 9(09) X(32) 9(09) PIC X(16) COMP. COMP VALUE 32. VALUE SPACES. COMP VALUE 16. VALUE SPACES. ... LINKAGE SECTION. 01 IO-PCB. 02 ... 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 3.1: Restart statement This example declares variable AREA-1 and the contents of structure AREA-2 as required for restart. Field CHKP-ID is set to blanks before the restart statement. After its completion, field CHKP-ID w ill either be blank, indicating normal start, or contain the identifier of the restart checkpoint. Checkpoint Request (CHKP & CCHK Function Codes) The checkpoint statement requests that all database updates issued in the current unit of recovery are committed to the databases, and defines w hich areas w ithin the program are required for restart. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- CHKP ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+ >--------------.------------------------------------.----------------->< | | | .----------------------------. | | | | | | v | | +---.--- area length --- area ---.---+ >>--- CCHK ---.--- i/o pcb ---.--- i/o area len --- i/o area ----------> +--- i/o aib ---+ >--------------.------------------------------------.------------------>< | | | .----------------------------. | | | | | | v | | +---.--- area length --- area ---.---+ DL/I Diagram 3.5: Checkpoint request SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 33 Description CHKP The name of an area in your program that contains the 4 byte function code “CHKP”. CCHK The name of an area in your program that contains the 4 byte function code “CCHK”. Use “CCHK” w hen you require feedback as to whether SPICE DL/I suppressed the checkpoint. Further discussion may be found in item Checkpoint Facilities on page 17. i/o pcb The name of the area in your program that contains the I/O PCB, the first PCB in the PCB list. i/o aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the character value “IOPCB ”. The routine name “AIBTDLI” must be used. i/o area len The name of an area in your program that contains the 4 byte binary length of the longest segment (or path of segments) of your program. i/o area The name of the I/O area in your program. It must be at least 12 bytes long. The first 8 bytes should be set to an identifier for the checkpoint. Upon restart the identifier of the restart checkpoint is notified to the operator. The identifier need not be unique, w ithin the program's checkpoints, or betw een programs. The follow ing 4 bytes are used w hen the “CCHK” function code is specified. If the program is to be tested under the BTS program product, the I/O area should be at least 80 bytes long. area len The name of an area in your program that contains the 4 byte binary length of the follow ing area parameter. area The name of an area in your program, w hose contents are required for restart. You may specify up to 7 program restart areas. Their number and lengths must be such that they can be restored w ithin the areas defined in the restart statement. 34 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Notes Before conveying a checkpoint to IMS, SPICE w ill save the follow ing: • The contents of the declared program areas. • Positioning information for all GSAM files. • The contents of the database PCB key feedback areas. SPICE DL/I Checkpoint Suppression After the DL/I CHKP statement the resultant status code should be examined. Failures excepted, it will alw ays take the value of blanks. As the program is unaw are of suppressed checkpoints, it should assume that database position has been lost, and reposition its databases before proceeding. For most programs the CHKP function code is entirely satisfactory. It is possible, how ever, that the overhead of redundant database re-positioning becomes unacceptable. To cater for this situation, SPICE DL/I introduces the CCHK function code. If function code CCHK is used, the program w ill be informed, as follow s: • If the checkpoint is suppressed, a binary value of 4 w ill be returned in the 4 bytes follow ing the checkpoint identifier in the I/O area. • If the checkpoint is processed by IMS, a binary value of 0 will be returned. The program can use this indicator to decide as to whether it is necessary to reposition its databases. SPICE DL/I Forced Checkpoint The application program can force SPICE to issue a checkpoint statement to IMS, by issuing a second checkpoint statement, w ithout any intervening processing. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 35 Examples 01 FUNC-CHKP 01 MAX-PATH-LEN 01 IOAREA. 02 CHKP-ID 02 FIELD-1 02 FIELD-2 01 AREA-1-LEN 01 AREA-1 01 AREA-2-LEN 01 AREA-2. 02 FIELD-1 PIC X(04) PIC 9(09) PIC PIC PIC PIC PIC PIC VALUE 'CHKP'. COMP VALUE 128. X(08). 9(09) X(68). 9(09) X(32) 9(09) PIC X(16) COMP. COMP VALUE 32. VALUE SPACES. COMP VALUE 16. VALUE SPACES. ... LINKAGE SECTION. 01 IO-PCB. 02 ... 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 3.2: Issue a checkpoint (CHKP function code) The example issues a checkpoint request. The value in field CHKP-ID is the identifier of the checkpoint. The contents of field AREA-1 and structure AREA-2 contain data that is required for restart. The program w ill reposition its databases after the checkpoint statement. 01 FUNC-CCHK 01 MAX-PATH-LEN 01 IOAREA. 02 CHKP-ID 02 FIELD-1 02 FIELD-2 01 AREA-1-LEN 01 AREA-1 01 AREA-2-LEN 01 AREA-2. 02 FIELD-1 PIC X(04) PIC 9(09) PIC PIC PIC PIC PIC PIC X(08). 9(09) X(68). 9(09) X(32) 9(09) PIC X(16) VALUE 'CCHK'. COMP VALUE 128. COMP. COMP VALUE 32. VALUE SPACES. COMP VALUE 16. VALUE SPACES. ... LINKAGE SECTION. 01 IO-PCB. 02 ... 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 3.3: Issue a checkpoint (CCHK function code) The example issues a checkpoint request. The value in field CHKP-ID is the identifier of the checkpoint. The contents of field AREA-1 and structure AREA-2 contain data that is required for restart. After the checkpoint statement the program w ill examine field FIELD-1 of IOAREA , to determine if its databases should be re-positioned. 36 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 01 FUNC-CHKP 01 MAX-PATH-LEN 01 IOAREA. 02 CHKP-ID 02 FIELD-1 02 FIELD-2 01 AREA-1-LEN 01 AREA-1 01 AREA-2-LEN 01 AREA-2. 02 FIELD-1 PIC X(04) PIC 9(09) PIC PIC PIC PIC PIC PIC VALUE 'CHKP'. COMP VALUE 128. X(08). 9(09) X(68). 9(09) X(32) 9(09) PIC X(16) COMP. COMP VALUE 32. VALUE SPACES. COMP VALUE 16. VALUE SPACES. ... LINKAGE SECTION. 01 IO-PCB. 02 ... 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 3.4: Force a checkpoint The example forces a checkpoint. The value in field CHKP-ID is the identifier of the checkpoint. The contents of field AREA-1 and structure AREA-2 contain data that is required for restart. The program will reposition its databases after the checkpoint statement. SPICE DL/I Rollback Request (ROLB Function Code) The rollback statement requests that all database updates issued in the current unit of recovery are not committed to the databases. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- ROLB ---.--- i/o pcb ---.---.----------------.------------------>< +--- i/o aib ---+ +--- i/o area ---+ DL/I Diagram 3.6: Rollback uncommitted updates Description ROLB The name of an area in your program that contains the 4 byte function code “ROLB”. i/o pcb The name of the area in your program that contains the I/O PCB, the first PCB in the PCB list. i/o aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the character value “IOPCB ”. The routine name “AIBTDLI” must be used. i/o area The I/O area is only required for message driven BMPs. It defines the name of an area in your program into which the message segment is to be returned. It is not appropriate to restartable programs, and should be omitted. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 37 Notes After the rollback statement, SPICE w ill allow the application program to restart. To retain synchronization betw een the databases, program areas and SPICE GSAM files, the program should reissue the restart statement. It w ill recover the contents of its program areas to their state at the last successful checkpoint. The SPICE GSAM files w ill be automatically re-positioned to that point. See SPICE In-Flight Restart™ on page 5 for more information. Examples 01 FUNC-ROLB PIC X(04) VALUE 'ROLB'. ... LINKAGE SECTION. 01 IO-PCB. 02 ... i/o pcb layout ... PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB, ... ... CALL 'CBLTDLI' USING FUNC-ROLB, IO-PCB. COBOL Example 3.5: Issue rollback request to abandon uncommitted updates The example w ill cancel all updates issued since the previous checkpoint. In-Flight Restart Initialization Request (INIT Function Code) If a SPICE DL/I program is required to use SPICE in-flight restart to recover from deadlock conditions, IMS requires that an ‘INIT’ statement be issued during initialisation. IMS w ill then return a 'BC' status codes, in the event of a deadlock. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- INIT ---.--- i/o pcb ---.--- i/o area -------------------------->< +--- i/o aib ---+ DL/I Diagram 3.7: DL/I initialization (INIT ) Description INIT The name of an area in your program that contains the 4 byte function code “INIT”. i/o pcb The name of the area in your program that contains the I/O PCB, the first PCB in the PCB list. i/o aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the character value “IOPCB ”. The routine name “AIBTDLI” must be used. i/o area The name of an area in your program. It must contain the value “STATUS GROUPB”. 38 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Notes Follow ing this statement, w hen IMS detects a DL/I database deadlock, requiring the backing out of the uncommitted updates of your program, IMS returns a PCB status code of “BC”, rather than terminating the program. Your application program may w ish to respond by invoking SPICE in-flight restart. Further information may be found in topic SPICE In-Flight Restart™ on page 5. Examples 01 FUNC-INIT 01 STATUS-GROUPB PIC X(04) PIC X(16) VALUE 'INIT'. VALUE 'STATUS GROUPB'. ... LINKAGE SECTION. 01 IO-PCB. 02 ... i/o pcb layout ... PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB, ... ... CALL 'CBLTDLI' USING FUNC-INIT, IO-PCB, STATUS-GROUPB. COBOL Example 3.6: DL/I initialization statement (INIT ) The example instructs IMS to return a PCB status code of “BC”, w hen backout occurs due to deadlock. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 39 Sequential File Processing This section describes the follow ing aspects of SPICE DL/I: • • • • • • • SPICE SPICE GSAM GSAM GSAM GSAM GSAM DL/I GSAM PCBs & AIBs on page 40 DL/I GSAM File Record Processing on page 42 File Open Request (OPEN Function Code) on page 43 File Sequential Read Request (GN Function Code) on page 44 File Reposition & Read Request (GU Function Code) on page 45 File Write Request (ISRT Function Code) on page 46 File Close Request (CLSE Function Code) on page 47 SPICE DL/I GSAM PCBs & AIBs Application programs request SPICE DL/I Sequential File processing by issuing DL/I calls against GSAM PCBs or AIBs. GSAM PCB Layout SPICE DL/I file processing uses the same PCB layout as IMS GSAM. Examples follow , for some of the supported languages. COBOL 01 PCBNAME. 02 DBD-NAME 02 SEG-LEVEL 02 STATUS-CODE 02 PROC-OPTIONS 02 RESERVE-DLI 02 SEG-NAME-FB 02 LENGTH-KEY-FB 02 NUMB-SENS-SEGS 02 KEY-FB-AREA 02 LENGTH-U-REC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC X(8). X(2). X(2). X(4). S9(5) X(8). S9(5) S9(5) X(8). S9(5) COMP. COMP. COMP. COMP. COBOL Diagram 3.8: GSAM PCB layout PL/I DECLARE 1 PCBNAME 2 DBD-NAME 2 SEG-LEVEL 2 STATUS-CODE 2 PROC-OPTIONS 2 RESERVE-DLI 2 SEG-NAME-FB 2 LENGTH-KEY-FB 2 NUMB-SENS-SEGS 2 KEY-FB-AREA 2 LENGTH-U-REC BASED (PCB-POINTER), CHAR(8), CHAR(2), CHAR(2), CHAR(4), FIXED BIN(31,0), CHAR(8), FIXED BIN(31,0), FIXED BIN(31,0) CHAR(8), FIXED BIN(31,0); PL/I Diagram 3.9: GSAM PCB layout 40 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Pascal type CHAR2 CHAR4 CHAR8 = packed array[1..2] of CHAR; = packed array[1..4] of CHAR; = packed array[1..8] of CHAR; PCBTYPE = record DBD-NAME SEG-LEVEL STATUS-CODE PROC-OPTIONS RESERVE-DLI SEG-NAME-FB LENGTH-KEY-FB NUMB-SENS-SEGS KEY-FB-AREA LENGTH-U-REC end; :CHAR8; :CHAR2; :CHAR2; :CHAR4; :INTEGER; :CHAR8; :INTEGER; :INTEGER; :CHAR8; :INTEGER; Pascal Diagram 3.10: GSAM PCB layout C struct { char char char char int char int int char int db_name[8]; seg_level[2]; stat_code[2]; proc_opt[4]; _dli; seg_name_fb[8]; len_kfb; nu_senseg; key_fb_area[8]; len_u_rec; } pcbname; C Language Diagram 3.11: GSAM PCB layout Assem bler Language GSPCB GSPCBDBD GSPCBLEV GSPCBSTC GSPCBPRO GSPCBRSV GSPCBSFD GSPCBLKY GSPCBNSS GSPCBKFD GSPCBLUR DSECT DS DS DS DS DS DS DS DS DS DS CL8 CL2 CL2 CL4 F CL8 F F F F DBD NAME SEGMENT LEVEL STATUS CODE PROCESSING OPTIONS RESERVED FOR DLI SEGMENT NAME FEEDBACK KEY LENGTH NO. OF SENSITIVE SEGMENTS KEY FEEDBACK LEVEL UNDEFINED RECORD LENGTH Assembler Language Diagram 3.12: GSAM PCB layout AIB Support SPICE DL/I supports DL/I statements using the AIB interface against GSAM files. SPICE also allow s the application to issue AIB requests for GSAM files that are not defined in the PSB. The first request against such an AIB must be to open the file, using the OPEN function code. The database name specified in the AIB is used as the file DD name. SPICE DL/I w ill allocate a PCB for the application. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 41 SPICE DL/I Processing of File DD Name Whenever possible, SPICE DL/I w ill use the DD name(s) defined in the GSAM DBD to satisfy a DL/I request to a GSAM DBD. Otherw ise, it w ill use the DBD name as DD name. The follow ing table defines SPICE DL/I processing of GSAM DD names: Situation DBD not found No file allocated to DD nam e specified in DBD Otherwise File Processed by SPICE DL/I T he file allocated to the DD statement with the same name as the DBD. If DD name not found, SPICE DL/I will return a status code of “ AI” to the request. T he file allocated to the DD name defined in the GSAM DBD. T able 3.1: SPICE DL/I DD name selection SPICE DL/I GSAM File Record Processing 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 w ritten. Variable Length Records The binary record length is stored in a 2 byte prefix to the record. The 2 bytes of the prefix is included in the length. Undefined Length Records The length of undefined length records is communicated in a field in the PCB (offset hex 2C). The field is named as LENGTH-U-REC ( len_u_rec for C, GSPCBLUR for Assembler) in the layouts detailed in topic SPICE DL/I GSAM PCBs & AIBs on page 40. 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. 42 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 GSAM File Open Request (OPEN Function Code) SPICE GSAM files are opened in SPICE DL/I w ith a DL/I statement to a GSAM PCB, using the OPEN function code. If the program omits to open the file explicitly, SPICE DL/I w ill open it upon the first DL/I statement that references it. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- OPEN ---.--- gsam pcb ---.---.----------------.----------------->< +--- gsam aib ---+ +--- i/o area ---+ DL/I Diagram 3.13: Open GSAM file Description OPEN The name of an area in your program that contains the 4 byte function code “OPEN”. gsam pcb The name of the area in your program that contains the GSAM PCB. gsam aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the name of the GSAM DBD. The routine name “AIBTDLI” must be used. i/o area (optional) The name of an area in your program that contains one of the follow ing character values. • “INP” for an input data set. • “OUT” for an output data set. • “OUTA ” for an output data set w ith ASA control characters. • “OUTM” for an output data set w ith machine control characters. Notes If the request is the first reference to the GSAM PCB follow ing a restart, SPICE DL/I w ill automatically reposition the file to its position at the restart checkpoint. Examples 01 FUNC-OPEN 01 INDIC-OUTPUT PIC X(04) PIC X(04) VALUE 'OPEN'. VALUE 'OUT'. ... LINKAGE SECTION. 01 GSAM-PCB. 02 GSAM-DBD PIC X(08). 02 ... gsam pcb layout ... PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB, ..., GSAM-PCB. ... CALL 'CBLTDLI' USING FUNC-OPEN, GSAM-PCB, INDIC-OUTPUT. COBOL Example 3.7: Open GSAM output file The example opens the GSAM output file associated w ith GSAM PCB GSAM-PCB. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 43 GSAM File Sequential Read Request (GN Function Code) To read the next sequential record from a SPICE GSAM file, issue a DL/I statement using the GN function code. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- GN ---.--- gsam pcb ---.--- i/o area ---.-----------.--------->< +--- gsam aib ---+ +--- rsa ---+ DL/I Diagram 3.14: Read record from GSAM file (GN function code) Description GN The name of an area in your program that contains the 4 byte function code “GN ”. gsam pcb The name of the area in your program that contains the GSAM PCB. gsam aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the name of the GSAM DBD. The routine name “AIBTDLI” must be used. i/o area The name of the area in your program into which SPICE DL/I should place the requested record from the file. The record length of variable length records may be found in the first two bytes of the I/O area. The record length of undefined length records may be found in the last 4 bytes of the PCB, offset hex 2C. Further information may be found in topic SPICE DL/I GSAM File Record Processing on page 42. rsa (optional) The name of an 8 byte area in your program, into w hich SPICE DL/I should place the record search argument (RSA) of the record retrieved by SPICE DL/I. This value may be used in a subsequent GU request, to retrieve the record out of sequence. Notes If the request is the first reference to the GSAM PCB follow ing a restart, SPICE DL/I w ill automatically reposition the file to its position at the restart checkpoint. If all the records in the file have been read, a status code of “GB” is returned in the PCB. 44 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Examples 01 FUNC-GN 01 REC-IN-AREA. 02 FIELD-1 PIC X(04) VALUE 'GN '. PIC X(16) VALUE SPACES. ... LINKAGE SECTION. 01 GSAM-PCB. 02 GSAM-DBD PIC X(08). 02 ... gsam pcb layout ... PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB, ..., GSAM-PCB. ... CALL 'CBLTDLI' USING FUNC-GN, GSAM-PCB, REC-IN-AREA. COBOL Example 3.8: Read record from input file (GN function code) The example reads the next record from the file associated w ith PCB GSAM-PCB, and stores it in structure REC-IN-AREA . SPICE DL/I w ill return a PCB status code of blanks if the record is successfully read. The value “GB” is returned if end of file is reached. GSAM File Reposition & Read Request (GU Function Code) To read a particular record, out of sequence, from a SPICE GSAM file, issue a DL/I statement using the GU function code, specifying the address of the record you require. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- GU ---.--- gsam pcb ---.--- i/o area --- rsa ----------------->< +--- gsam aib ---+ DL/I Diagram 3.15: Re-position GSAM file and read record (GU function code) Description GU The name of an area in your program that contains the 4 byte function code “GU ”. gsam pcb The name of the area in your program that contains the GSAM PCB. gsam aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the name of the GSAM DBD. The routine name “AIBTDLI” must be used. i/o area The name of the area in your program into which SPICE DL/I should place the requested record from the file. The record length of variable length records may be found in the first two bytes of the I/O area. The record length of undefined length records may be found in the last 4 bytes of the PCB, offset hex 2C. Further information may be found in topic SPICE DL/I GSAM File Record Processing on page 42. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 45 rsa The name of an 8 byte area in your program, that contains the record search argument (RSA) of the required record. The RSA should have been obtained from the prior GU or ISRT statement that originally processed the required record. Examples 01 FUNC-GU 01 REC-IN-AREA. 02 FIELD-1 01 RSA PIC X(04) VALUE 'GU '. PIC X(16) VALUE SPACES. PIC X(08). ... LINKAGE SECTION. 01 GSAM-PCB. 02 GSAM-DBD PIC X(08). 02 ... gsam pcb layout ... PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB, ..., GSAM-PCB. ... CALL 'CBLTDLI' USING FUNC-GU, GSAM-PCB, REC-IN-AREA, RSA. COBOL Example 3.9: Re-position input file and read record (GU function code) The example reads the record from the file associated w ith PCB GSAM-PCB, w hose address is stored in field RSA . The record is stored into structure REC-IN-AREA . GSAM File Write Request (ISRT Function Code) To w rite the next sequential record to a SPICE GSAM file, issue a DL/I statement using the ISRT function code. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- ISRT ---.--- gsam pcb ---.--- i/o area ---.-----------.--------->< +--- gsam aib ---+ +--- rsa ---+ DL/I Diagram 3.16: Write record to GSAM file (ISRT function code) Description ISRT The name of an area in your program that contains the 4 byte function code “ISRT”. gsam pcb The name of the area in your program that contains the GSAM PCB. gsam aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the name of the GSAM DBD. The routine name “AIBTDLI” must be used. i/o area The name of the area in your program from w hich SPICE DL/I should w rite the requested record to the file. The record length of variable length records should be placed in the first two bytes of the I/O area. The record length of undefined length records should be placed in the 46 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 last 4 bytes of the PCB, offset hex 2C. Further information may be found in topic SPICE DL/I GSAM File Record Processing on page 42. rsa (optional) The name of an 8 byte area in your program, into w hich SPICE DL/I should place the record search argument (RSA) of the record w ritten by SPICE DL/I. This value may be used in a subsequent GU request, to retrieve the record out of sequence. Notes If the request is the first reference to the GSAM PCB follow ing a restart, SPICE DL/I w ill automatically reposition the file to its position at the restart checkpoint. Examples 01 FUNC-ISRT 01 REC-OUT-AREA. 02 FIELD-1 PIC X(04) VALUE 'ISRT'. PIC X(16) VALUE SPACES. ... LINKAGE SECTION. 01 GSAM-PCB. 02 GSAM-DBD PIC X(08). 02 ... gsam pcb layout ... PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB, ..., GSAM-PCB. ... CALL 'CBLTDLI' USING FUNC-ISRT, GSAM-PCB, REC-OUT-AREA. COBOL Example 3.10: Writ e record from output file (ISRT function code) The example writes the next record to the file associated w ith PCB GSAM-PCB, from structure REC-OUT-AREA . GSAM File Close Request (CLSE Function Code) SPICE GSAM input files are closed in SPICE DL/I w ith a DL/I statement to a GSAM PCB, using the CLSE function code. If the program omits to close the file explicitly, SPICE DL/I w ill close it upon the termination of the program. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- CLSE ---.--- gsam pcb ---.-------------------------------------->< +--- gsam aib ---+ DL/I Diagram 3.17: Close GSAM file Description CLSE The name of an area in your program that contains the 4 byte function code “CLSE”. gsam pcb The name of the area in your program that contains the GSAM PCB. gsam aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the name of the GSAM DBD. The routine name “AIBTDLI” must be used. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 47 Examples 01 FUNC-CLSE PIC X(04) VALUE 'CLSE'. ... LINKAGE SECTION. 01 GSAM-PCB. 02 GSAM-DBD PIC X(08). 02 ... gsam pcb layout ... PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB, ..., GSAM-PCB ... CALL 'CBLTDLI' USING FUNC-CLSE, GSAM-PCB. COBOL Example 3.11: Close GSAM input file The example closes the GSAM input file associated w ith GSAM PCB GSAM-PCB. 48 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Services This section describes the follow ing aspects of SPICE DL/I: • • SPICE Program Testing Facility on page 49 SPICE Test Request on page 50 SPICE Program Testing Facility 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 w here the programmer w ishes to test a failure. The facility is controlled by DD statements in the application JCL. These JCL statements, typically assigned to DUMMY , define w hat action SPICE is to perform w hen the application issues a SPICE services test statement, abnormally terminate for instance. When the controlling DD statement is removed, the SQL statement w ill process successfully. It is thereby possible to design a suite of JCL that tests thoroughly the restart logic of a program. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 49 SPICE Test Request The SPICE Services Test Facility is requested from SPICE DL/I by issuing a DL/I statement using the TEST function code. The parameter list to the DL/I statement contains the follow ing elements. For a description of this layout, see SPICE DL/I Statement Layout Conventions on page 30. >>--- TEST ---.--- i/o pcb ---.---.----------------.------------------>< +--- i/o aib ---+ +--- i/o area ---+ DL/I Diagram 3.18: SPICE services test facility Description TEST The name of an area in your program that contains the 4 byte function code “TEST”. i/o pcb The name of the area in your program that contains the I/O PCB. i/o aib Alternatively, the AIB interface may be used. To so do, specify this parameter as the name of an AIB control block. AIB field AIBRSNM1 must contain the value “IOPCB ”. The routine name “AIBTDLI” must be used. i/o area (optional) The name of an area in your program that identifies the DD names that are used to control the testing facility. The first 5 characters of the value are used to determine the DD names that control the testing facility. If omitted, SPICE w ill use the default value, “SPIOT”. Notes The SPICE Services Test Facility is controlled via the existence of certain DD names in the program JCL. They are assigned typically to DUMMY . For a DD name prefix of “A1234”, SPICE processing w ill be controlled by the follow ing DD names: //A1234DIE DD DUMMY If this DD name is found in the program JCL, SPICE w ill immediately Abend w ith code 4090. //A1234ERR DD DUMMY If this DD name is found in the program JCL, SPICE w ill return a PCB status code of “ZZ ”. 50 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Examples 01 FUNC-TEST 01 TEST-PREFIX PIC X(04) VALUE 'TEST'. PIC X(05) VALUE 'TESTS'. ... LINKAGE SECTION. 01 IO-PCB. 02 ... i/o pcb layout ... PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB, ... ... CALL 'CBLTDLI' USING FUNC-TEST, IO-PCB, TEST-PREFIX. COBOL Example 3.12: Request the SPICE services test facility (T EST function code) The example will request the SPICE DL/I services testing facility. The action SPICE w ill take depends upon the job JCL DD statements. SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 51 SPICE DL/I Statement Parameter Summary This section describes the follow ing aspects of SPICE DL/I programming: • • • Checkpoint & Restart Statements on page 52 GSAM Sequential File Management Statements on page 53 SPICE Services Statements on page 53 For a description of these layouts, see SPICE DL/I Statement Layout Conventions on page 30. Checkpoint & Restart Statements >>--- XRST ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+ >--------------.------------------------------------.----------------->< | | | .----------------------------. | | | | | | v | | +---.--- area length --- area ---.---+ >>--- CHKP ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+ >--------------.------------------------------------.----------------->< | | | .----------------------------. | | | | | | v | | +---.--- area length --- area ---.---+ >>--- CCHK ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+ >--------------.------------------------------------.----------------->< | | | .----------------------------. | | | | | | v | | +---.--- area length --- area ---.---+ >>--- ROLB ---.--- i/o pcb ---.---.----------------.------------------>< +--- i/o aib ---+ +--- i/o area ---+ 52 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 >>--- INIT ---.--- i/o pcb ---.--- i/o area -------------------------->< +--- i/o aib ---+ GSAM Sequential File Management Statements >>--- OPEN ---.--- gsam pcb ---.---.----------------.----------------->< +--- gsam aib ---+ +--- i/o area ---+ >>--- GU ---.--- gsam pcb ---.--- i/o area --- rsa ----------------->< +--- gsam aib ---+ >>--- ISRT ---.--- gsam pcb ---.--- i/o area ---.-----------.--------->< +--- gsam aib ---+ +--- rsa ---+ >>--- CLSE ---.--- gsam pcb ---.-------------------------------------->< +--- gsam aib ---+ SPICE Services Statements >>--- TEST ---.--- i/o pcb ---.---.----------------.------------------>< +--- i/o aib ---+ +--- i/o area ---+ SPICE™ Application Programming with SPICE DL/I™ 18 June 2009 © 1993,2009 Span Software Consultants Limited 53 54 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Chapter 4. SPICE DL/I™ Application Administration This chapter describes how to administer SPICE DL/I Application Programs. • • Restart Database Administration on page 55 Application Program Administration on page 63 Restart Database Administration This segment describes how to create and administer SPICE DL/I Restart Databases. • • • • • • • IMS SPICE Restart Database Naming Rules on page 55 IMS System Preparation on page 56 IMS Restart Database Creation on page 56 IMS PSB Preparation on page 59 IMS Restart Database Considerations on page 60 SPICE Restart Database Security on page 61 SPICE Restart Database Maintenance on page 61 IMS SPICE Restart Database Naming Rules SPICE DL/I supports three types of database organisation for its IMS SPICE Restart Databases, namely HDAM, DEDB and MSDB. SPICE requires that the first five characters of the database must be: ! ! ! SPICH SPICD SPICM HDAM SPICE Restart Databases. DEDB SPICE Restart Databases. MSDB SPICE Restart Databases. Any values may be chosen for the remaining characters. SPICE DL/I™ Restart Dat abase Administration 18 June 2009 © 1993,2009 Span Software Consultants Limited 55 IMS System Preparation The IMS HDAM SPICE Restart Database must be defined to the IMS system. The follow ing statement, amended to specify the selected name, should be included in the IMS generation: Database definition statem ents DATABASE DBD=SPIC**** If the database data sets are to be dynamically allocated by IMS, dynamic allocation definitions should be prepared and generated. IMS Restart Database Creation These are the types of SPICE DL/I Restart Database that you can create: • • • 56 HDAM Restart Database Creation on page 57 DEDB Restart Database Creation on page 58 MSDB Restart Database Creation on page 59 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 HDAM Restart Database Creation The follow ing steps should be performed, to create an HDAM SPICE Restart Database: 1) 2) 3) 4) 5) 6) 7) 8) 9) 10) Create • • • and compile the database DBD. The name of the database must begin w ith “SPICH”. The length of the SPIDPSB segment must not be altered. The length of the SPIDCHK segment may be changed, to suit the characteristics of the application program(s) that w ill use the database. Define the database to the IMS system that will use it. Define the database to DBRC, and incorporate it into your database backup and recovery system. Allocate the database and define appropriate security. Create or modify a PSB, to include a load PCB for the new database. Create a dynamic allocation definition for the new database, if required. Initialize the database, using the PSB from the earlier step. Topic SPICE DL/I Restart Database Initialization on page 122, details how this may be done. Add a PCB for the database to all the required SPICE utility program and subsystem PSBs. Include a PCB for the database in all application PSBs that are to use it. Topic IMS Application PSB Preparation on page 65, details how this may be done. Generate ACBs as necessary. The follow ing members of the SPICE DL/I sample library, SPICE.SPI31.SAMPLIB, contain JCL and source data that can be adapted to create and initialize an IMS HDAM SPICE Restart Database. Library Me m be r Nam e Note s SPICHSAM Sample DBD source for IMS HDAM SPICE restart database. SPIDBPSB Sample PSB source, including a load PCB for an IMS HDAM SPICE restart database. SPICHLOD Sample JCL for allocating and initializing an IMS HDAM SPICE restart database. SPICE messages SPI0412I and SPI0107W may be issued. T able 5.1: IMS HDAM SPICE restart database installation SPICE DL/I™ Restart Dat abase Administration 18 June 2009 © 1993,2009 Span Software Consultants Limited 57 DEDB Restart Database Creation The follow ing steps should be performed, to create a DEDB SPICE Restart Database: 1) 2) 3) 4) 5) 6) 7) 8) 9) 11) 10) Create • • • and compile the DBD for the database. The database name must begin w ith the characters “SPICD”. The length of the SPIDPSB segment must not be altered. The length of the SPIDCHK segment may be changed, to suit the characteristics of the application program(s) that w ill use the database. • All segments in a DEDB are of variable length: an IMS restriction. How ever, SPICE alw ays inserts and replaces its segments at their maximum length. This optimizes IMS Fast Path replace performance. Define the database to the IMS system that will use it. Define the database to DBRC, and incorporate it into your database backup and recovery system. Allocate the database and define appropriate security. Initialize the database w ith the Fast Path DEDB initialization utility. Add a PCB for the database to all the required SPICE utility program and subsystem PSBs. Generate ACBs as necessary. Create a dynamic allocation definition for the new database, if required. Start the IMS system. If the system is already running, issue an IMS /START DB command against the database. Initialize the database, using a utility PSB from the earlier step. Topic IMS Application PSB Preparation on page 65, details how this may be done. Include a PCB for the database in all application PSBs that are to use it. Topic IMS Application PSB Preparation on page 65, details how this may be done. Generate ACBs as necessary. The follow ing members of the SPICE DL/I sample library, SPICE.SPI31.SAMPLIB, contain JCL and source data that w ill create and initialize an IMS DEDB SPICE Restart Database. Library Me m be r Nam e Note s SPICDSAM Sample DBD source for IMS DEDB SPICE restart database. SPIFPPSB Sample PSB source, including a PCB for an IMS DEDB SPICE restart database. SPICDLOD Sample JCL for allocating an IMS DEDB SPICE restart database. SPICDLO2 Sample JCL for init ializing an IMS DEDB SPICE restart database. SPICE messages SPI0412I and SPI0107W may be issued. N.B. IMS must be active for this job. T able 5.2: IMS DEDB SPICE restart database installation 58 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 MSDB Restart Database Creation The follow ing steps should be performed, to create an MSDB SPICE Restart Database: 1) 2) 3) 4) 5) 6) 7) 8) 9) 10) Create and compile the DBD for the database. • The database name must begin w ith the characters “SPICM”. • MSDB databases may only have one segment type, of fixed length. SPICE maps its logical structure onto these segments. • The length of the SPIDMSDB segment may be changed, to suit the characteristics of the application program(s) that w ill use the database. Define the database to the IMS system that will use it. Generate the MSDB initialization load file, using the MSDB maintenance utility. The sample job allocates a database of 25 entries. Increase this as appropriate, indexing each entry w ith its sequence number. Add a PCB for the database to all the required SPICE utility program and subsystem PSBs. Generate ACBs as necessary. Define appropriate security. Restart the IMS system, loading up the new MSDB from the initialization file generated in the earlier step. Initialize the database, using a utility PSB containing the new database. Topic IMS Application PSB Preparation on page 65, details how this may be done. Incorporate the database into your MSDB backup and recovery system. Include a PCB for the database in all application PSBs that are to use it. Topic IMS Application PSB Preparation on page 65, details how this may be done. Generate ACBs as necessary. The follow ing members of the SPICE DL/I sample library, SPICE.SPI31.SAMPLIB, contain JCL and source data that w ill create and initialize an IMS MSDB SPICE Restart Database. Library Me m be r Nam e Note s SPICMSAM Sample DBD source for IMS MSDB SPICE restart database. SPIFPPSB Sample PSB source, including a PCB for an IMS MSDB SPICE restart database. SPICMLOD Sample JCL for allocating an IMS MSDB SPICE restart database. SPICMLO2 Sample JCL for init ializing an IMS MSDB SPICE restart database. SPICE messages SPI0412I and SPI0107W may be issued. N.B. IMS must be active for this job. T able 5.3: IMS MSDB SPICE restart database installation IMS PSB Preparation PCBs for the SPICE Restart Databases should be included in the PSBs used by the SPICE operator subsystem and the SPICE utility program. SPICE DL/I™ Restart Dat abase Administration 18 June 2009 © 1993,2009 Span Software Consultants Limited 59 IMS Restart Database Considerations When designing the database arrangements for SPICE DL/I, the follow ing considerations should be review ed. SPICE Restart Database usage Typically, SPICE Restart Databases are not large, and SPICE applications do not place a heavy load upon them. As w ith any other database how ever, database usage should be regularly monitored, and action taken as necessary. Number of SPICE Restart Databases SPICE places no restrictions on the number of SPICE Restart Databases in an IMS system. This facilitates the separation of testing data from production, or the separation of data by project. We suggest one SPICE Restart Database per project as a good compromise betw een administrative convenience, w hich favours the minimum number, and minimising the consequences of a component failure, which favours the maximum. The constraints on sharing SPICE Restart Databases, imposed by IMS, are as follow s: BM P Applications More than one executing BMP can share the same SPICE Restart Database. It is, therefore, possible for SPICE Restart Databases to be shared betw een application projects. The SPICE Restart Database is an attractive candidate for the Fast Path multiple area dataset DEDB option, provided the application never executes in batch. Batch Applications For SPICE applications that run as IMS batch programs in a serial stream, one SPICE Restart Database per project is possible. If, how ever, the project applications are so structured that multiple restartable jobs run at the same time, it will be necessary to have one for each separate strand. Tw o alternatives are suggested. The application could be executed as BMPs, or IMS database block level sharing may be used for the SPICE Restart Database. 60 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Restart Database Security As w ith any other database, adequate steps should be taken to ensure that the SPICE Restart Databases can be recovered, in the event of irreparable failure. As regards access security, the follow ing table gives the level of access to the SPICE Restart Database required by different categories of use. acce ss Use full • SPICE Restart Database administrator read and write • • SPICE application programs System Administ ration personnel t asked to administ er SPICE applications, e.g. to issue SPICE Ut ility update commands such as CHANGE read only • System Administ ration personnel t asked to monit or SPICE applications, e.g. to issue SPICE Utility display commands T able 5.4: SPICE Restart Database access By default, SPICE relies for security on customer control of access to the SPICE libraries and the SPICE Restart Databases. Should further security be required, the SPICE utility security exit, detailed in SPICE Getting Started, can be used to control access to the commands of the SPICE Operator Subsystem and the SPICE Utility program. SPICE Restart Database Maintenance Deleting Inactive SPICE Restart Database Entries Over time it is likely that entries w ill accumulate in the SPICE Restart Database for PSBs and jobs that are no longer run. Such entries can be deleted from the tables w ith the SPICE operator facilities. WARNING Great care should be taken with this facility! By default, SPICE w ill not delete entries for PSBs and jobs that are active. It does, how ever, include options for deleting such entries. Note that incorrect use of this option can cause catastrophic application program failure. See topic Restart Database Maintenance on page 124, for details how this may be done. SPICE DL/I™ Restart Dat abase Administration 18 June 2009 © 1993,2009 Span Software Consultants Limited 61 SPICE MSDB Restart Database Repair SPICE DL/I includes a facility for marking individual entries in an IMS MSDB SPICE Restart Database as available for allocation by SPICE DL/I. WARNING Great care should be taken with this option! This facility should only be used under guidance from the SPICE supplier. Incorrect use of this command can cause catastrophic application program failure. See topic SPICE MSDB Restart Database Repair on page 125, for details how this may be done. 62 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Application Program Administration This section describes how SPICE DL/I application programs should be prepared for execution. • • • • • Application Program Compile and Link-Edit on page 63 Run Time Environments on page 65 IMS Application PSB Preparation on page 65 Sequential Dataset Allocation on page 66 Application Program JCL on page 67 Application Program Compile and Link-Edit The follow ing example illustrates the JCL required to compile and link edit a SPICE DL/I application program. Omit the ‘INCLUDE’ and ‘//LKED.SPILIB’ statememnts if the follow ing are all true: • The link-editor Automatic Library Call option (CALL) is in use. • The SPICE load library ‘SPICE.SPI31SYS.SPILOAD’ is the first library in the ‘SYSLIB’ concatenation. SPICE DL/I™ Restart Dat abase Administration 18 June 2009 © 1993,2009 Span Software Consultants Limited 63 The follow ing table gives details of the SPICE DL/I modules that may need to be linkedited w ith customer applications. SPICE m odule Notes SPIDHLI0 The SPICE DL/I High Level Interface routine (HLI) • This handles DL/I and SQL statements. • Required for separately link-edited modules invoked during a program’s execution if one of the follow ing applies: • The module issues the first DL/I statement in the execution. • The module issues SQL statements. SPIXLEUX The SPICE Language Environment (LE) User Exit (CEEBXITA) • Required for application programs that execute in z/OS LE enclaves. T able 5.5: SPICE Link-edit Included Modules z/OS Language Environment (LE) Considerations The successful execution of SPICE applications requires that SPICE be informed of application termination, normal or abnormal. This enables SPICE to indicate the application’s successful completion in the SPICE Restart Database. Failure to so do can result in application failure. In z/OS Language Environment Enclaves, this is performed via the SPICE implementation of the z/OS Language Environment Assembler exit, CEEBXITA. The exit resides in the SPICE load library, ‘SPICE.SPI31.SPILOAD’. If a program is to execute in an LE enclave, but cannot be linked to include the SPICE LE User Exit, module SPIXLEUX, the program must be executed w ith the follow ing LE options: • TRAP(OFF,NOSPIE) 64 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Run Time Environments Under SPICE DL/I, application programs can execute in the follow ing environments: • IMS BMP or IMS batch regions. When both SPICE SQL and SPICE DL/I are installed, SQL application programs that do not issue DL/I statements can execute in the follow ing environments: • The TSO DB2 command processor, DSN, in foreground and background. • Other compatible call attachment facility environments. The follow ing table illustrates the supported environments: Installed SPICE Products Issue DL/I statement s Execute in IMS regions Execute under DB2 DSN SPICE DL/I yes no SPICE SQL no yes yes no SPICE SQL & SPICE DL/I yes yes yes in IMS regions only. Issue SQL statements yes, but SPICE does not monitor them for restart critical events, e.g. backout. yes T able 5.6: SPICE Supported Environments IMS Application PSB Preparation The SPICE DL/I application PSB must contain a PCB for the SPICE Restart Database. If the PCB is to appear in the PCB list presented to the application program, it should be coded as the last database PCB, before the GSAM PCBs. The program w ill have to include it in its specification of the contents of the PCB list. Alternatively, the PCB may be hidden. This is done by specifying “LIST=NO” and “PCBNAME=SPICREST” on the PCB statement in the PSB. If SPICE SQL is installed, and it is wished that SPICE should use the DB2 SPICE Restart Database for this PSB, the database DBD name should be prefixed “SPICR”. The actual definition of the IMS database of this name w ill be ignored by SPICE DL/I. Alternatively, use of the SPICE SQL Restart Database may be forced by including a DD statement in the JCL w ith name SPIOFDB2, w hich may be allocated to DUMMY. SPICE DL/I™ Restart Dat abase Administration 18 June 2009 © 1993,2009 Span Software Consultants Limited 65 Sequential Dataset Allocation Sequential datasets that are to be processed via SPICE should be allocated explicitly in the job JCL. The choice of DD name for processing is defined in item SPICE DL/I GSAM PCBs & AIBs on page 40. Types of dataset supported by SPICE DL/I are defined in item Sequential File Programming Considerations on page 20. SPICE GSAM output files In order that the JCL required for restart be unaltered from the initial JCL, SPICE GSAM output datasets should be pre-allocated in earlier job steps. It is recommended, for ease of operation, that they are allocated in separate jobs. Furthermore, before being w ritten to by SPICE, SPICE GSAM files must be initialized w ith DCB information, including blocksize. For tape files it is necessary to create the tape label. This is most easily performed by copying an end of file to the tape. The follow ing example illustrates the JCL required to allocate disk and tape SPICE GSAM files. //DISK EXEC //SYSUT1 DD //SYSUT2 DD // // // //SYSPRINT DD //SYSIN DD //* //TAPE EXEC //SYSUT1 DD //SYSUT2 DD // // //SYSPRINT DD //SYSIN DD PGM=IEBGENER DSN=SPICE.SPI31.SAMPLIB(PPURTX4),DISP=SHR DISP=(NEW,CATLG),DSN=SPICE.SPI31IVP.SE1DATA.SSAMFB, UNIT=3390,VOL=SER=SPIVOL, SPACE=(TRK,(1,1)), DCB=(LRECL=80,BLKSIZE=160,RECFM=FB) DUMMY DUMMY PGM=IEBGENER DSN=SPICE.SPI31.SAMPLIB(PPURTX4),DISP=SHR DISP=(NEW,CATLG),DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB, UNIT=TAPE,VOL=SER=SPISTV,FILE=(1,SL), DCB=(RECFM=FBA,LRECL=80,BLKSIZE=8000) DUMMY DUMMY JCL Example 5.1: Allocate SPICE GSAM sequential files 66 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Application Program JCL IMS BMP Execution of SPICE Application The follow ing example illustrates the JCL required to run an application program controlled by SPICE DL/I, as a BMP. //PROCPURC // //STEPLIB // // //SYSPRINT //IMS // //SPIUDUMP //CEEDUMP //SE1PRINT //SE1DATA EXEC IMSBATCH,MBR=my-pgm,PSB=my-psb, IMSID=IVP1 DD DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR DD DSN=my.load.library,DISP=SHR DD SYSOUT=* DD DISP=SHR,DSN=my-dbdlib DD DISP=SHR,DSN=my-psblib DD SYSOUT=* DD SYSOUT=* DD DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB,DISP=SHR DD DSN=SPICE.SPI31IVP.SE1DATA.SSAMFB,DISP=SHR JCL Example 5.2: Application program execution (BMP) Consult IMS documentation for further information on IMS BMP JCL. IMS BMP Execution of SPICE SQL Application The follow ing example illustrates the JCL required to run an application program controlled by SPICE DL/I and SPICE SQL, as a BMP. //PROCPURC // //STEPLIB // // // //DFSRESLB //DFSESL // //SPIOFDB2 //SYSPRINT //IMS // //SPIUDUMP //CEEDUMP //SE1PRINT //SE1DATA EXEC IMSBATCH,MBR=my-pgm,PSB=my-psb, IMSID=IVP1 DD DD DSN=DSN.SDSNLOAD,DISP=SHR DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR DD DSN=my.load.library,DISP=SHR DD DSN=IMS.SDFSRESL,DISP=SHR DD DSN=IMS.SDFSRESL,DISP=SHR DD DSN=DSN.SDSNLOAD,DISP=SHR DD DUMMY DD SYSOUT=* DD DISP=SHR,DSN=my-dbdlib DD DISP=SHR,DSN=my-psblib DD SYSOUT=* DD SYSOUT=* DD DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB,DISP=SHR DD DSN=SPICE.SPI31IVP.SE1DATA.SSAMFB,DISP=SHR JCL Example 5.3: SPICE SQL application program execution (BMP) Consult IMS and DB2 documentation for further information on IMS BMP JCL and the IMS attachment facility. SPICE DL/I™ Restart Dat abase Administration 18 June 2009 © 1993,2009 Span Software Consultants Limited 67 IMS Batch Execution of SPICE Application The follow ing example illustrates the JCL required to run an application program controlled by SPICE DL/I, as an IMS batch program. //PROCPURC // //STEPLIB // // //IEFRDER //SPIUDUMP //CEEDUMP //SE1PRINT //SE1DATA //SPICHSAM // EXEC DLIBATCH, MBR=my-pgm,PSB=my-psb DD DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR DD DSN=my.load.library,DISP=SHR DD ... my IMS log DD SYSOUT=* DD SYSOUT=* DD DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB,DISP=SHR DD DSN=SPICE.SPI31IVP.SE1DATA.SSAMFB,DISP=SHR DD DSN=SPICE.SPI31IVP.SPICHSAM.DBASE,DISP=SHR ... my data bases JCL Example 5.4: Application program execution (IMS batch) Consult IMS documentation for further information on IMS batch JCL. JCL Considerations The requirements specific to SPICE are as follow s: The IMS procedure should include an allocation of the IMS DBD library, assigned to DD name IMS. //S TEPLIB Ensure that the STEPLIB concatenation conforms w ith Run Time Environments on page 65. S PICE.S PI31S YS .S PILOAD The name of the load library dataset into which SPICE DL/I w as installed. S PICE GS AM files Any physical sequential disk or tape file can be read or w ritten by SPICE, w ith full SPICE restart support. S PICE GS AM tape output files SPICE requires that DCB information for SPICE GSAM tape output files, including RECFM, LRECL and BLKSIZE, be specified on the DD statement explicitly. Other S PICE GS AM file types SPICE DL/I can also process the follow ing file types: • Concatenated input files. • Partitioned data set (PDS) members. • JES input files (“//... DD *”) and JES output files (“//...DD SYSOUT=”). • TSO files (“ALLOC ... DA(*)”). SPICE must be able to ascertain the file record type, length and block size. It may be necessary to specify the DCB information explicitly, including block size, on the DD statement. Furthermore, SPICE cannot re-position these files, and will issue warning message SPI0012W. //S PIUDUMP ... Should an abend occur during the execution of a SPICE DL/I application program, SPICE w ill generate a formatted dump of its control data. The DCB requirements for this dataset are record format VBA and record length 125. When no SPIUDUMP DD statement exists, SPICE w ill allocate a SYSOUT=A dataset dynamically. //S PIOFDB2 The existence of this DD name instructs SPICE DL/I to use the SPICE SQL Restart Database. Alternatively, include a PCB in the PSB for a database w hose name begins w ith the characters SPICR. IMS procedure 68 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 //<prefix>DIE //<prefix>ERR //<prefix>OK These DD names are used to control the SPICE services test facility. The 5 character prefix is specified by the application program. The default is “SPIOT”. They should be used only in testing environments. The operation of the facility is described in topic SPICE Services Test Facility on page 116. z/OS Language Environment (LE) Considerations See Application Program Compile and Link-Edit on page 63. SPICE DL/I™ Restart Dat abase Administration 18 June 2009 © 1993,2009 Span Software Consultants Limited 69 70 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Chapter 5. SPICE DL/I™ Operation This chapter describes how SPICE DL/I should be used by personnel responsible for the operation of systems using SPICE DL/I. • • • • • • • • • Introduction to SPICE Operation on page 71 SPICE Operational Responsibilities on page 73 Using the SPICE TSO/ISPF Operator Subsystem on page 75 Using the SPICE Utility Program on page 79 SPICE Restart Database Reports on page 83 SPICE DL/I Application Program Execution on page 96 Controlling SPICE Features on page 106 Other Facilities on page 122 SPICE Utility Command Summary on page 128 Introduction to SPICE Operation 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. This section consists of the follow ing topics: • • • Background on page 71 SPICE TSO/ISPF Operator Subsystem on page 72 SPICE Utility Program on page 72 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, w ithout 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 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 w ith 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 DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 71 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. 72 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Operational Responsibilities This section summarizes the uses to w hich the SPICE operator facilities can be put by various categories of installation personnel. This section consists of the follow ing topics: • • • Operations Personnel on page 73 Development Personnel on page 74 Database Administration and Technical Support Personnel on page 74 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 follow ing: • • To monitor the state of applications, by using the SPICE reporting options. To restart SPICE DL/I jobs, follow ing 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 follow ing: • • 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 w ith 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 follow ing: • • To register new application programs in the SPICE Restart Database. To control w hich SPICE facilities are to be used. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 73 Development Personnel Staff responsible for developing SPICE DL/I applications can use the facilities of SPICE for the follow ing: • • • To monitor the state of their application programs, by using the SPICE reporting options. To control w hich SPICE facilities are to be used, according to the current testing requirements of a program. Follow ing 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 follow ing: • • 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. 74 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Using the SPICE TSO/ISPF Operator Subsystem This section serves as an introduction to the SPICE TSO/ISPF utility subsystem supplied as part of SPICE DL/I. It is intended solely as a simple introduction. The intuitive nature of the subsystem, in conjunction with its extensive help and tutorial panels, w ill enable the user quickly to use the subsystem w ithout reference to printed documentation. This section consists of the follow ing topics: • • Getting Started on page 75 A Brief Guide on page 77 Getting Started The SPICE operator subsystem is accessed typically from the ISPF primary options menu; the panel that you see w hen you start ISPF. It is possible, how ever, that the SPICE operator subsystem w as installed into some other option menu. If you do not know how to select the SPICE operator subsystem, consult your SPICE administrator. When the SPICE Operator Subsystem is selected, the follow ing menu panel is presented to the user: ========================= SPICE Operator Subsystem =========================== OPTION ===> ------------------ SSSSSSSSSSSSSS iii SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS --------------- SSSSSSSSSSSSSSSSS iii SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS ------------- SSSS SSSS ------------ SSSS ppppppp iii ccccc eeeeee SSSS ------------- SSSS ppp ppp iii ccc ccc eee eee --------------- SSSS ppp ppp iii ccc eeeeeeee ------------------ SSSS ppp ppp iii ccc ccc eee Operator ----------- SSSS --- SSSS ppppppp iiiii ccccc eeeeee Subsystem ----------- SSSS --- SSSS ppp ------------SSSSSSSSSSSSS ppp Copyright (C) 1993,2004 -------------SSSSSSSSS ppp SPAN Software Consultants Limited ----------------- 0 OPTIONS - Set SPICE Operator Subsystem options T TUTORIAL - Tutorial on SPICE and its Operator Subsystem Enter END to exit Figure 5.1: SPICE Operator Subsystem Primary Options Menu Panel The SPICE operator subsystem includes extensive help and tutorial facilities. To obtain help from any point in the subsystem, type “HELP” and press enter, or press the function key assigned to HELP, usually PF1. Note also that the tutorial can be selected from the primary options panel (option TUTORIAL). SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 75 When the user selects the SPICE operator subsystem for the very first time, option 1 ( SPICE) w ill not be displayed. It is necessary first to tell SPICE w hich IMS system you w ish SPICE to connect to. Select option 0 ( OPTIONS) to do this. The follow ing menu panel is displayed: ========================= SPICE Operator Subsystem =========================== OPTION ===> _ --------------------------- Configuration Options ---------------------------1 SYSTEM TABLE - Configure SPICE system table X EXIT - Return Enter Enter to process Enter END to exit Figure 5.2: SPICE Operator Subsystem Configuration Options Menu Panel Select option 1 ( SYSTEM TABLE). The follow ing table panel is displayed: ========================= SPICE Operator Subsystem ================ ROW 1 OF 2 OPTION ===> _ SCROLL ===> PAGE ---------------------------- SPICE System Table -----------------------------Line commands: Select entry List entry Edit entry Insert entry Delete Enter END to exit System Command Status Name Type Description current IVP1 IMS IMS test system PIMS IMS IMS production system ******************************* BOTTOM OF DATA ********************************* Figure 5.3: SPICE Operator Subsystem System T able Panel Type “S” in the Command column alongside the system you w ish to connect to, and press Enter . The system you have selected w ill now have the indicator “current” displayed alongside it. This system w ill be connected to when subsequently w e select option 1 ( SPICE) from the primary options menu. Should the system you require not be displayed, you should consult w ith your SPICE administrator. The facilities for altering the contents of the system table are detailed in topic SPICE Operator Subsystem Installation of manual SPICE SQL & SPICE DL/I Installation Manual. Return to the SPICE operator subsystem primary option menu. 76 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 A Brief Guide We shall now have a short guided tour of the SPICE operator subsystem. From the SPICE operator subsystem primary option menu, select option 1 ( SPICE). The follow ing menu panel is displayed: ========================= SPICE Operator Subsystem =========================== OPTION ===> _ ------------------------------- Master Menu ---------------------------------1 2 3 DB PROGRAM/PSB JOB - Select Database entries - Select Program(DB2) / PSB(IMS) Entries - Select Job entries 4 COMMAND - Free form command input Enter END to exit from SPICE Operator Subsystem Figure 5.4: SPICE Operator Subsystem Master Menu Panel We now have a choice of processing a table of SPICE Restart Databases ( DB), a table of all PSB entries from all the databases ( PROGRAM/PSB), or a table of all job entries for all PSBs in all SPICE Restart Databases ( JOB). The last option ( COMMAND) allow s us to enter SPICE utility commands through the SPICE operator subsystem. Database Table Processing Options If w e select option 1 ( DB) from the master menu, SPICE w ill display the follow ing table panel: ========================= SPICE Operator Subsystem ================ ROW 1 OF 1 OPTION ===> _ SCROLL ===> PAGE -------------------------- SPICE DataBase Table -----------------------------Line commands: Select entry List database defaults Edit database defaults Initialise entry DUMP database defaults MSDB Select as MSDB database Enter END to exit Database Command Name Type Description SPICDSAM DEDB IMS DEDB RESTART DATABASE SPICHSAM HDAM IMS HDAM RESTART DATABASE SPICMSAM MSDB IMS MSDB RESTART DATABASE ******************************* BOTTOM OF DATA ********************************* Figure 5.5: SPICE Operator Subsystem Dat abase T able Panel The database table panel allow s access to the default values entry of the databases. We can use its options to examine and alter them. We can also initialize an empty database for use by SPICE. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 77 PSB Table Processing Options If w e select option 2 ( PROGRAM/PSB) from the master menu SPICE w ill display the follow ing PSB table panel. There will be row s in the table for all PSBs registered in each of the databases. ========================= SPICE Operator Subsystem ================ ROW 1 OF 2 OPTION ===> _ SCROLL ===> PAGE -------------------------- SPICE Program/PSB Table --------------------------Line commands: Select entry List entry Edit entry Insert entry DELETE entry DUMP entry SUSPEND program/PSB RELEASE suspend Enter END to exit Program/ Command PSB Name -----------SPICE Status---------------------SPIDBPCB SPIDCPSB SPIVP4CP ******************************* BOTTOM OF DATA ********************************* Figure 5.6: SPICE Operator Subsystem Program T able Panel Note that the SELECT option of the database table panel can also be used to select a PSB table panel. In this case, row s w ill exist for all PSBs registered in the selected database. The PSB table panel allow s us access to the PSB entries of the selected database(s). We can use its options to examine and alter them. We can also register new PSBs to SPICE. Job Table Processing Options If w e select option 3 ( JOB) from the master menu SPICE w ill display the follow ing job table panel. There w ill be row s in the table for all the job entries of every registered PSB in each database. ========================= SPICE Operator Subsystem ================ ROW 1 OF 3 OPTION ===> _ SCROLL ===> PAGE ----------------------------- SPICE Job Table -------------------------------Line commands: List entry Edit entry DELETE entry DUMP entry RESTART job RERUN job SUSPEND job RELEASE Suspend Enter END to exit Status Last Commit/Checkpoint Data Command Jobname Stepname ---------------- Identifier Timestamp Total SAMPUTI1 SPIUTIL SPI00005 2004.028 09:34:12. 5 SAMPJOB1 PROCPURC ACTIVE SPI00008 2004.030 14:20:33.4 13 SAMPJOBB PROCPURC SPI00013 2004.029 17:16:29.4 17 ******************************* BOTTOM OF DATA ********************************* Figure 5.7: SPICE Operator Subsystem Job T able Panel Note that the SELECT option of the PSB table panel can also be used to select a job table panel. In this case, row s w ill exist for all jobs of the selected PSB. The job table panel allow s us access to the job entries of the selected PSB(s). We can use its options to examine and alter them. This is the end of our little tour around the SPICE operator subsystem. We have only introduced the bare elements of the system. The reader is invited to continue to w ander around the options from the panels w e have met. It is recommended that the help system be used to explain the purpose of all the various options and subsidiary panels. 78 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Using the SPICE Utility Program This section serves as an introduction to the utility program supplied as part of SPICE DL/I. Topics covered include the execution of the utility, the conventions used w hen building commands for it, and the HELP command. This section consists of the follow ing topics: • • • SPICE Utility Program Execution on page 79 SPICE Utility Program Command Conventions on page 81 SPICE Utility Program Help Command on page 82 SPICE Utility Program Execution The SPICE utility is a program that is used to manage the contents of the SPICE Restart Database. IMS BMP Execution of SPICE Utility The follow ing JCL, customized to local standards, may be used to execute the SPICE utility program as an IMS BMP. //JOBCARD JOB (ACCT),USER.NAME,CLASS=A,NOTIFY=USER,MSGCLASS=A //* //* DOC: EXAMPLE OF JCL TO EXECUTE THE SPICE UTILITY AS A BMP. //* //BMP EXEC IMSBATCH,MBR=SPIUTI00,PSB=SPIDCPSB //STEPLIB DD // DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SPIUDUMP DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * /*----------------------------------------------*/ /* SPICE UTILITY JCL EXAMPLE */ /*----------------------------------------------*/ LIST DBDNAME(SPICHSAM) /* GET REPORT OF ALL PROGRAMS */ PSBNAME(ALL) JOB(ALL) /* AND JOBS DEFINED IN THE */ /* SPICE RESTART DATABASE */ /* // Utility Example 5.1: SPICE DL/I Utility JCL (BMP) Consult IMS documentation for further information on IMS BMP JCL. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 79 IMS BMP Execution of SPICE Utility, attached to DB2 The follow ing JCL, customized to local standards, may be used to execute the SPICE utility program as an IMS BMP attached to a DB2 system. If SPICE SQL is installed, the program w ill be able to process both IMS and DB2 SPICE Restart Databases. //JOBCARD JOB (ACCT),USER.NAME,CLASS=A,NOTIFY=USER,MSGCLASS=A //* //* DOC: EXAMPLE OF JCL TO EXECUTE THE SPICE UTILITY AS A BMP, //* ATTACHED TO DB2. //* //BMP EXEC IMSBATCH,MBR=SPIUTI00,PSB=SPIDCPSB, // IMSID=IVP1,SSM=DSN1 //STEPLIB DD // DD DSN=DSN.SDSNLOAD,DISP=SHR // DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR //DFSRESLB DD DSN=IMS.SDFSRESL,DISP=SHR //DFSESL DD DSN=IMS.SDFSRESL,DISP=SHR // DD DSN=DSN.SDSNLOAD,DISP=SHR //SPIOFDB2 DD DUMMY //SYSPRINT DD SYSOUT=* //SPIUDUMP DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * /*----------------------------------------------*/ /* SPICE UTILITY JCL EXAMPLE */ /*----------------------------------------------*/ LIST DBDNAME(SPICHSAM) /* GET REPORT OF ALL PROGRAMS PSBNAME(ALL) JOB(ALL) /* AND JOBS DEFINED IN THE /* SPICE RESTART DATABASE LIST SQL /* GET REPORT OF ALL PROGRAMS PSBNAME(ALL) JOB(ALL) /* AND JOBS DEFINED IN THE /* DB2 RESTART DATABASE /* // */ */ */ */ */ */ - Utility Example 5.2: SPICE DL/I Utility JCL (BMP + DB2) Consult IMS and DB2 documentation for further information on IMS BMP JCL and the IMS attachment facility. IMS Batch Execution of SPICE Utility The follow ing JCL, customized to local standards, may be used to execute the SPICE utility program as an IMS batch program. //JOBCARD JOB (ACCT),USER.NAME,CLASS=A,NOTIFY=USER,MSGCLASS=A //* //* DOC: EXAMPLE OF JCL TO RUN THE SPICE UTILITY IN BATCH. //* //BATCH EXEC DLIBATCH,MBR=SPIUTI00,PSB=SPIDBPSB //STEPLIB DD // DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR //SPICHSAM DD DSN=SPICE.SPI31IVP.SPICHSAM.DBASE,DISP=SHR //DFSVSAMP DD DSN=SPICE.SPI31.SAMPLIB(SPIVVSAM),DISP=SHR //SYSPRINT DD SYSOUT=* //SPIUDUMP DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * /*----------------------------------------------*/ /* SPICE UTILITY JCL EXAMPLE */ /*----------------------------------------------*/ LIST DBDNAME(SPICHSAM) /* GET REPORT OF ALL PROGRAMS */ PSBNAME(ALL) JOB(ALL) /* AND JOBS DEFINED IN THE */ /* SPICE RESTART DATABASE */ /* // Utility Example 5.3: SPICE DL/I Utility JCL (batch) Consult IMS documentation for further information on IMS batch JCL. 80 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 JCL Considerations The PSB used should contain PCB's for the SPICE databases that the user w ishes to process. S PICE.S PI31S YS .S PILOAD The name of the load library dataset into w hich SPICE DL/I w as installed. //S YS PRINT ... The SPICE utility command responses and reports are w ritten to this DD name. The reports are described in section SPICE Restart Database Reports on page 83. //S YS IN ... The SPICE utility commands are read from this DD name. The next topic describes the rules for constructing these commands. //S PIOFDB2 ... The existence of this DD name instructs SPICE to access the DB2 SPICE Restart Database. Alternatively, include a PCB in the PSB for a database w hose name begins w ith the characters SPICR. Note that SPICE will not issue any calls to this database. Only use these options if SPICE SQL is installed. psb name SPICE Utility Program Command Conventions All commands of the SPICE utility program must adhere to the syntax rules defined here. The syntax is similar to that used in TSO/E and the VSAM Access Method Services utility program. The follow ing considerations apply when coding commands for the SPICE utility program: • • • • • • • Columns 73-80 are ignored. Commands and their operands can begin in any column. Comments can be included in a command by enclosing them by “/*”. . .“*/”. Blanks, commas or comments may be used in a command, w herever a separator is required. Commands may be continued onto one or more lines. There are two continuation characters, “-” and “+”. Commands are continued by coding a continuation character as the last non-blank character in the line. A plus sign w ill ignore any leading blanks from the follow ing line. A minus sign w ill not. Blank lines betw een commands are ignored. Command parameters must be enclosed in quotes if they are to contain characters other than “A”-“Z”, “0”-“9”, “#”, “@”, “%” and the currency symbols. To represent a quote in a string code it tw ice. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 81 The follow ing example illustrates the command layout conventions: /* /* THIS IS A COMMENT */ SO IS THIS */ /*--------------------------------*/ /* THE FOLLOWING LIST COMMAND */ /* ILLUSTRATES THE SPICE UTILITY */ /* PROGRAM COMMAND CONVENTIONS */ /*--------------------------------*/ LIST /* WORDS MAY BE SPLIT */ /* COMMANDS MAY BE SPLIT */ DBDNAME(SPICHSAM) /* ACROSS LINES AND EVEN */ PSBNAME(ABC+ 123) + JOBNAME('@ODDNAME') Utility Example 5.4: Command conventions SPICE Utility Program Help Command SPICE includes a HELP command. The follow ing diagram defines the command and its options: >>--- HELP ---.------------.-------------------------------------------->< +-- CHANGE --+ +-- DELETE --+ +-- HELP ----+ +-- INIT ----+ +-- LIST ----+ +-- REPRO ---+ +-- SET -----+ Utility Diagram 5.1: HELP command The simple form of the command, w ithout any options, generates a report of a list of commands available. Specifying a command name as the option generates a description of that command. Specifying the option HELP generates a description of the conventions used in describing the command options. Exam ples /*-------------------------------------*/ /* HELP COMMAND EXAMPLES */ /*-------------------------------------*/ HELP /* LIST OF AVAILABLE COMMANDS HELP LIST /* LIST OF LIST COMMAND OPTIONS */ HELP /* EXPLANATION OF COMMAND /* DESCRIPTION TERMINOLOGY HELP */ */ */ Utility Example 5.5: HELP command 82 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 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 w ith the LIST option (SPICE operator subsystem) or LIST command (SPICE utility). The SPICE Restart Database contains the follow ing entry types: PSB Entries Define the SPICE options that are to be used w hen the named PSB is executed w ith SPICE. Job Entries 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. Default Values Entry Defines certain SPICE options that are to be used for PSBs that are designated as using these default values. This section consists of the follow ing topics: • • • • PSB Entry Reports on page 84 Job Entry Reports on page 87 Default Values Entry Report on page 92 MSDB Restart Database Contents Report on page 94 SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 83 PSB Entry Reports SPICE Operator Subsystem A report on the contents of a PSB entry in the SPICE Restart Database can be obtained from the SPICE operator subsystem by selecting the LIST option against its entry in the PSB table. A formatted dump of the entry can be obtained by selecting the DUM P option. SPICE Utility Command The follow ing diagram defines the variant of the LIST command that will report on the contents of selected PSB entries in the SPICE Restart Database. >>--- LIST --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >------------- PSBNAME --- ( -.- name -.- ) ------------------------------> +- ALL -+ >--------------.-------------.--.----------.------------------------------->< +-- FORMAT --+ +-- DUMP --+ Ut ility Diagram 5.2: LIST command for PSB entries PS BNAME(ALL) FORMAT DUMP Select all PSB entries in the database. A one line report on each entry w ill be generated. Generate a formatted report from the selected entries. This is the default when a specific entry is selected. Generate a hexadecimal dump of the contents of the selected entries. Exam ples /*-------------------------------------*/ /* LIST DBD... PSB ... EXAMPLES */ /*-------------------------------------*/ LIST DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* FORMATTED REPORT OF A /* SPECIFIC PSB ENTRY */ */ - LIST DBDNAME(SPICHSAM) PSBNAME(ALL) /* LIST OF ALL PSB'S */ /* DEFINED IN THE RESTART */ /* DATABASE (ONE PER LINE) */ LIST DBDNAME(SPICHSAM) PSBNAME(ALL) FORMAT /* FORMATTED REPORT OF ALL */ /* PSB'S DEFINED IN THE */ /* RESTART DATABASE */ LIST DBDNAME(SPICHSAM) PSBNAME(SPIUTI00) FORMAT DUMP /* FORMATTED REPORT AND /* HEXADECIMAL DUMP OF A /* SPECIFIC PSB ENTRY */ */ */ Ut ility Example 5.6: LIST commands for PSB entries 84 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Formatted Report Contents The follow ing example is an instance of a formatted report of a PSB entry. PSB SPIVP4CP entry created 2004.286 restart entry length 2030 last change 0000.000 0:00:00.0 Commit Point Suppression (DEFAULT VALUES) thresholds: seconds updates DB2 & IMS BMP regions 30 1000 IMS BATCH regions 900 10000 Application Timeout (DEFAULT VALUES) WTO upon application timeout thresholds: seconds updates DB2 & IMS BMP regions 300 10000 IMS BATCH regions 0 0 Commit Point Braking (DEFAULT VALUES) wait period: seconds DB2 & IMS BMP regions 0 IMS BATCH regions 0 In-Flight Restart (DEFAULT VALUES) Terminate Out of Sync -Keep Restart loop detection limit restarts 5 Report Example 5.7: Formatted Report of PSB Entry PS B The name of the application program. entry created, last change The date and time w hen the entry w as created and last altered by SPICE operator facilities. restart entry length Length of job entry segment. Commit Point S uppression Values of SPICE checkpoint suppression parameters. The Application Timeout Commit Point Braking In-Flight Restart loop detection limit Terminate Out of S ync values labelled DB2 & IMS BMP regions apply w hen the PSB is run as a BMP. The values labelled IMS BATCH regions apply w hen the PSB is run as batch IMS. This section of the report is further explained in topic Checkpoint Suppression on page 107. Values of SPICE application timeout parameters. The values labelled DB2 & IMS BMP regions apply w hen the PSB is run as a BMP. The values labelled IMS BATCH regions apply w hen the PSB is run as batch IMS. This section of the report is further explained in topic Application Program Timeout on page 110. Values of SPICE checkpoint braking parameters. The values labelled DB2 & IMS BMP regions apply w hen the PSB is run as a BMP. The values labelled IMS BATCH regions apply w hen the PSB is run as batch IMS. This section of the report is further explained in topic Checkpoint Braking on page 116. The maximum number of SPICE In-Flight Restarts that may be issued w ithout an intervening successful checkpoint. This section of the report is further explained in topic SPICE InFlight Restart ™ on page 113. The action that SPICE w ill take upon program termination w hen the restart resources are out of synchronization, follow ing a ‘ROLB’ for instance. This option is further explained in Application Program Termination on page 119. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 85 Other Indicators (when present) S US PENDED RES TART DIS ABLED (DEFAULT VALUES ) Indicates that execution of the PSB under SPICE has been suspended. Absence of this text indicates that the PSB can execute. This feature is further explained in topic Interrupting Application Program Execution on page 104. Indicates that SPICE restart w ill not be available for this PSB. This indicator should only ever be set in testing environments. Absence of this text indicates that SPICE restart is available for this PSB. This feature is further explained in topic Disabling SPICE Restart on page 123. Indicates that the parameters used to control this feature are taken from the default values entry in the database. Absence of this text indicates that SPICE w ill take its parameters from the PSB entry. Further information can be found in topic Default Value Processing on page 106. Dump Report Contents The follow ing example is an instance of a dump of the contents of a PSB entry. This report option is intended for diagnostic purposes only. PSB SPIVP4CP The dump of the Entry Header: +0000 00640064 +0010 00000000 +0020 D7F4C3D7 +0030 0000000C +0040 00000000 +0050 E2D7C9E5 +0060 00050000 entry follows: E2D7E2C2 00000000 2004286F 000007EE 00000000 D7F4C3D7 00000000 51200000 00000000 00000000 00000000 40404040 27100000 E2D7C9E5 0000000C 00000000 00000000 40404040 *....SPSB........* *............SPIV* *P4CP...?........* *................* *................* *SPIVP4CP * *....* Report Example 5.8: DUMP Report of PSB Entry 86 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Job Entry Reports The data in a job entry represents a particular execution of the PSB. It includes all data required for any restarts that may occur, follow ing program failure. SPICE Operator Subsystem A report on the contents of a job entry in the SPICE Restart Database can be obtained from the SPICE operator subsystem by selecting the LIST option against its entry in the job table. A formatted dump of the entry can be obtained by selecting the DUM P option. SPICE Utility Command The follow ing diagram defines the variant of the LIST command that will report on the contents of job entries in the SPICE Restart Database. >>--- LIST --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >------------- PSBNAME --- ( -.- name -.- ) ------------------------------> +- ALL -+ >------------- JOBNAME --- ( -.- name -.- ) ------------------------------> +- ALL -+ >--------------.------------.--.------------.--.----------.--------------->< +-- ACTIVE --+ +-- FORMAT --+ +-- DUMP --+ Ut ility Diagram 5.3: LIST command for job entries PS BNAME(ALL) JOBNAME(ALL) ACTIVE FORMAT DUMP Select all PSB entries in the database. A one line report on each entry w ill be generated. Select all job entries in the database for each selected PSB entry. A one line report on each entry w ill be generated. Select all job entries that are either executing or are aw aiting restart. Generate a formatted report on each of the selected entries. This is the default when a specific job entry is selected. Generate a hexadecimal dump of the contents of each of the selected entries. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 87 Exam ples /*---------------------------------------*/ /* LIST DBDNAME... JOBNAME ... EXAMPLES */ /*---------------------------------------*/ LIST DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) JOBNAME(ABC123) /* FORMATTED REPORT OF A /* SPECIFIC JOB ENTRY */ */ LIST DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) JOBNAME(ALL) /* /* /* /* LIST OF ALL JOBS DEFINED IN THE RESTART DATABASE FOR A SPECIFIC PSB (ONE PER LINE) */ */ + */ */ DBDNAME(SPICHSAM) PSBNAME(ALL) JOBNAME(ALL) /* /* /* /* LIST OF ALL JOBS AND PSB'S DEFINED IN THE RESTART DATABASE (ONE PER LINE) */ */ */ */ LIST LIST DBDNAME(SPICHSAM) PSBNAME(ALL) JOBNAME(ALL) ACTIVE /* LIST OF ALL ACTIVE JOBS */ /* DEFINED IN THE RESTART */ /* DATABASE (ONE PER LINE) */ LIST DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) JOBNAME(ALL) FORMAT /* /* /* /* FORMATTED REPORT OF ALL JOBS DEFINED IN THE RESTART DATABASE FOR A SPECIFIC PSB */ */ + */ */ DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) JOBNAME(ALL) FORMAT DUMP /* /* /* /* /* FORMATTED REPORT AND HEXADECIMAL DUMP OF ALL JOBS DEFINED IN THE RESTART DATABASE FOR A SPECIFIC PSB */ */ */ */ */ LIST + + - Ut ility Example 5.9: LIST commands for job entries 88 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Formatted Report Contents The follow ing example is an instance of a formatted report of a job entry. PSB SPIVP4CP JOB I63DIVBA I63DIVBA step G program SPIVCPUR entry created 2004.286 20:23:00.8 last change 0000.000 0:00:00.0 last start 2004.286 21:20:35.4 last restart 0000.000 0:00:00.0 last stop 2004.286 21:20:38.6 last commit 2004.286 21:20:38.6 identifier PPUR0008 Statistics: since job start commit points issued by program 9 commit points issued to DBMS 9 number database entries updated seconds elapsed since last start/restart 9 9 25 4 Report Example 5.10: Formatted Report of Job Entry The name of the job, the name of the step in its JCL and the program name. entry created, last change The date and time w hen the entry w as created and last altered by SPICE operator facilities. JOB, step, program last start, last restart, last finish The date and time w hen this execution of the program started, w as 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. last commit The time and date w hen the program last issued a checkpoint. identifier Identifier assigned to the checkpoint by the program. commit points ... program The number of checkpoints that the program has issued since last start and since the latest of last start and last restart. commit points ... DBMS 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 w ill never be higher those of the preceding line in the report. Note: The tw o columns only differ after a failure of the program has resulted in a restart, in w hich case the values in the first column will be higher. number ... entries updated The number of database entries that have been updated by the program since the latest of last start and last restart. seconds elapsed The time for w hich the program has been executing, in seconds, since the latest of last start and last restart. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 89 Other Indicators (when present) ACTIVE S US PENDED 90 This text, w hen present, indicates that the specified job is executing, or has failed and restart is required. SPICE w ill perform restart processing w hen the job is next executed. Absence of this text indicates that SPICE w ill perform normal start processing when the job is next executed. Indicates that execution of the program by this job under SPICE has been suspended. Absence of this text indicates that the program can execute under this job. This feature is further explained in topic Interrupting Application Program Execution on page 104. SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Dump Report Contents The follow ing example is an instance of a dump of the contents of a job entry. This report option is intended for diagnostic purposes only. It contains a dump of the contents of the program areas declared to SPICE as necessary for recovery. This data may be useful to programmers investigating application failures. JOB I63DIVBA The dump of the entry follows: Entry Header: +0000 07EE040C E2C3C8D2 00000000 00000000 *....SCHK........* +0010 00000000 00000000 00000000 C9F6F3C4 *............I63D* +0020 C9E5C2C1 F0F0F0F1 00AC0000 D7D7E4D9 *IVBA0001....PPUR* +0030 F0F0F0F8 2004286F 2023008F 2004286F *0008...?.......?* +0040 2120354F 0000000C 0000000C 2004286F *...|...........?* +0050 2120386F 2004286F 2120386F C9F6F3C4 *...?...?...?I63D* +0060 C9E5C2C1 C7404040 40404040 E2D7C9E5 *IVBAG SPIV* +0070 C3D7E4D9 00000019 00000158 00000009 *CPUR............* +0080 00000009 00000009 00000009 0000000C *................* +0090 0000000C 00000000 00000000 00000000 *................* +00A0 00000000 00000000 00000000 *............* restart item <SRRD> key <. . .0¯ > total length 0054(hex) prefix length 0034(hex) suffix length 0020(hex) Item prefix: +0000 00540000 E2D9D9C4 00159F18 00159E30 *....SRRD........* +0010 C1800000 00000100 00010004 F0BC4040 *A...........0. * +0020 40404040 40404040 0004F0BC 00000020 * ..0.....* +0030 00000004 *....* Item suffix: +0000 40404040 40404040 10004040 40404040 * .. * +0010 40404040 40404040 40404040 40404040 * * ... (items for this job omitted) restart item <SSPD> key <. . .êY > total length 00AC(hex) prefix length 007C(hex) suffix length 0030(hex) Item prefix: +0000 00AC0000 E2E2D7C4 00016720 00016318 *....SSPD........* +0010 94806891 10000100 0005000E 52E84040 *M..J.........Y * +0020 40404040 40404040 000E52E8 00000030 * ...Y....* +0030 0000004C 00000050 000000A0 00000F00 *...<...&........* +0040 00000000 00001301 00000000 00000000 *................* +0050 00000000 00000000 00000000 E2C5F1C4 *............SE1D* +0060 C1E3C140 E2C5F1C4 C1E3C140 E2C5F1C4 *ATA SE1DATA SE1D* +0070 C1E3C140 E2C5F1C4 C1E3C140 *ATA SE1DATA * Item suffix: +0000 E2C5F1C4 C1E3C140 00004040 C7E24040 *SE1DATA .. GS * +0010 000E52B0 C7E2C1D4 40404040 0000000C *....GSAM ....* +0020 0000FFFF 00000000 00000000 00000000 *................* ... (items for this job omitted) restart item <SPAD> key <. . > total length 004C(hex) prefix length 0038(hex) suffix length 0014(hex) Item prefix: +0000 004C0000 E2D7C1C4 00159698 00159598 *.<..SPAD..OQ..NQ* +0010 02809000 00000400 00014040 40404040 *.......... * +0020 40404040 40404040 800968A8 00000014 * ...Y....* +0030 00000008 00000014 *........* Item suffix: +0000 F0F0F0F0 F0F0F0F0 F0F1F2F0 F1F2F0F0 *0000000001201200* +0010 F1F0F0F0 *1000* restart item <SRIT> key <LAST ITEM > total length 0034(hex) prefix length 0034(hex) suffix length 0000(hex) Item prefix: +0000 00340000 E2D9C9E3 0011400C 00000000 *....SRIT.. .....* +0010 00200000 0000D3C1 E2E340C9 E3C5D440 *......LAST ITEM * +0020 40404040 40404040 00000000 00000000 * ........* +0030 00000004 *....* Report Example 5.11: DUMP Report of Job Entry SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 91 The name of the job, suffixed by blanks or, w hen restart data for this execution of the program is spread over multiple job entries, a sequence number. restart item <S S PD> key <value> The data in this item represents a SPICE SAM file. The DD name of the file is contained in the item dump. restart item <S PAD> key <area name> The data in this item represents a program area declared to SPICE as necessary for restart. The data headed item suffix is a dump of the contents of the program area, taken at the last successful checkpoint. There is one entry for each of the program restart areas notified to SPICE at that checkpoint. JOB Default Values Entry Report The values in the default values entry are used by SPICE w hen executing application programs w ith PSBs w hose SPICE Restart Database entries indicate that the default values are to be used. SPICE Operator Subsystem A report on the default SPICE values entry of the SPICE Restart Database can be obtained from the SPICE operator subsystem by selecting the LIST option against its entry in the database table. A formatted dump of the entry can be obtained by selecting the DUM P option. SPICE Utility Command The follow ing diagram defines the variant of the LIST command that will report on the default SPICE values entry in the SPICE Restart Database. >>--- LIST --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >------------- DEFAULTS --------------------------------------------------> >--------------.----------.----------------------------------------------->< +-- DUMP --+ Ut ility Diagram 5.4: LIST command for default value entries Generate a hexadecimal dump of the contents of the entry. DUMP Exam ples /*----------------------------------------*/ /* LIST DBDNAME... DEFAULTS EXAMPLES */ /*----------------------------------------*/ LIST DBDNAME(SPICHSAM) DEFAULTS /* FORMATTED REPORT OF /* DEFAULT VALUES ENTRY */ */ LIST DBDNAME(SPICHSAM) DEFAULTS DUMP /* FORMATTED REPORT AND /* HEXADECIMAL DUMP OF /* DEFAULT VALUES ENTRY */ + */ */ Utility Example 5.12: LIST command for default values entry 92 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Formatted Report Contents The follow ing example is an instance of a formatted report of the default values entry. DEFAULT ENTRY entry created 2004.284 restart entry length 2030 Commit Point Suppression thresholds: DB2 & IMS IMS BATCH Application Timeout WTO upon application thresholds: DB2 & IMS IMS BATCH Commit Point Braking wait period: DB2 & IMS IMS BATCH In-Flight Restart loop detection limit last change 2004.284 17:45:31.6 BMP regions regions seconds 30 0 updates 1000 0 seconds 300 0 updates 10000 0 timeout BMP regions regions BMP regions regions seconds 0 0 Terminate Out of Sync -Keep Restart restarts 5 Report Example 5.13: Formatted Report of Default Values entry Indicates that this is the default values entry. The date and time w hen the database w as initialized. The date and time when the entry w as last altered by SPICE utility command. restart entry length Length of job entry segment. Commit Point S uppression Values of SPICE checkpoint suppression parameters used w ith PSB's w hose database entries specify use of the default values. The values labelled DB2 & IMS BMP regions apply w hen the PSB is run as a BMP. The values labelled IMS BATCH regions apply w hen the PSB is run as batch IMS. This section of the report is further explained in topic Checkpoint Suppression on page 107. Application Timeout Values of SPICE application timeout parameters used w ith PSBs w hose database entries specify use of the default values. The values labelled DB2 & IMS BMP regions apply w hen the PSB is run as a BMP. The values labelled IMS BATCH regions apply w hen the PSB is run as batch IMS. This section of the report is further explained in topic Application Program Timeout on page 110. Commit Point Braking Values of SPICE checkpoint braking parameters used w ith PSBs w hose database entries specify use of the default values. The values labelled DB2 & IMS BMP regions apply w hen the PSB is run as a BMP. The values labelled IMS BATCH regions apply w hen the PSB is run as batch IMS. This section of the report is further explained in topic Checkpoint Braking on page 116. DEFAULT ENTRY entry created last change In-Flight Restart loop detection limit The maximum number of SPICE In-Flight Restarts that may be issued w ithout an intervening successful checkpoint. This section of the report is further explained in topic SPICE InFlight Restart ™ on page 113. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 93 Terminate Out of S ync The action that SPICE w ill take upon program termination w hen the restart resources are out of synchronization, follow ing a ‘ROLB’ for instance. This option is further explained in Application Program Termination on page 119. Dump Report Contents The follow ing example is an instance of a dump of the contents of the default values entry. This report option is intended for diagnostic purposes only. DEFAULT ENTRY The dump of the Entry Header: +0000 00640064 +0010 00000000 +0020 40404040 +0030 1745316F +0040 00000000 +0050 40404040 +0060 00050000 entry follows: E2D7E2C2 00000000 2004284F 000007EE 00000000 40404040 00000000 41200000 00000000 000003E8 00000000 40404040 27100000 40404040 2004284F 00000BB8 00000000 40404040 *....SPSB........* *............ * * ...|.......|* *...?.......Y....* *................* * * *....* Report Example 5.14: DUMP Report of Default Values entry MSDB Restart Database Contents Report The MSDB SPICE Restart Database contents report displays the current allocations of segments in the database. It can be used to assess how many free segments remain in the database. SPICE Operator Subsystem To obtain the MSDB contents report, select option MSDB against the database, from the database table panel. SPICE Utility Command The follow ing diagram defines the variant of the LIST command that will produce the MSDB contents report. >>--- LIST --- DBDNAME ---- ( --- name --- ) -----------------------------> >------------- MSDBINDEX -- ( -.- value -.- ) ----------------------------> +- ALL -+ >--------------.------------.--.----------.------------------------------->< +-- FORMAT --+ +-- DUMP --+ Utility Diagram 5.5: LIST command for MSDB contents report MS DBINDEX FORMAT DUMP 94 Specify ALL to report on all the entries in the database. The contents of a single entry may be obtained by specifying its index number. Generate a formatted report on each of the selected entries. This is the default when a specific entry is selected. Generate a hexadecimal dump of the contents of each of the selected entries. SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Exam ple /*---------------------------------------*/ /* LIST DBDNAME...MSDBINDEX... EXAMPLES */ /*---------------------------------------*/ LIST DBDNAME(SPICMSAM) MSDBINDEX(ALL) /* MSDB CONTENTS REPORT */ Ut ility Example 5.15: LIST command for MSDB entries Report Contents The follow ing example is an instance of an MSDB contents report. SPSB SPSB SPSB SCHK SCHK SCHK SCHK SCHK SPSB SCHK SCHK SCHK SCHK SCHK SCHK MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB SPIDCPSB SPIVP4CP JOBX JOBX JOBX JOBA JOBA SPIVP5CP JOBP JOBP JOBB JOBA JOBA JOBC 0001 0002 0003 0001 0002 0001 0002 0001 0001 0002 0001 ALLOCATED ALLOCATED ALLOCATED FREE FREE FREE ALLOCATED ALLOCATED ALLOCATED ALLOCATED ALLOCATED ALLOCATED FREE FREE FREE FREE FREE FREE FREE FREE FREE FREE FREE FREE FREE MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB MSDB 0001 0002 0003 0004 0005 0006 0007 0008 0009 0010 0011 0012 0013 0014 0015 0016 0017 0018 0019 0020 0021 0022 0023 0024 0025 across down across down across down 0007 across down across down across down across 0008 down across 0012 down across down 0010 across 0011 down across down across down across down across down across down across down across down across down across down across down across down across down across down across down across down Report Example 5.16: Formatted Report of Default Values entry S PS B/S CHK/MS DB ALLOCATED FREE MS DB nnnn across nnnn down nnnn Indicates that w hen the entry w as last allocated, it w as used as a PSB entry, a job entry or had never been allocated, respectively. The next item on the line is the name of the PSB, the name of the job and its index, or blanks, respectively. Indicates that the entry is currently allocated to a restart database entry. Indicates that the entry is available for use as a restart database entry. The index of the entry in the database. The index of the next ( SCHK) entry at the same hierarchical level. The index of the hierarchical child of this (SPSB) entry. The number of free entries may be calculated by adding up the number of entries flagged as FREE. The number of entries that have never been allocated, the number above the 'high w ater mark', may be calculated by adding up the number of entries not labelled as SPSB or SCHK. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 95 SPICE DL/I Application Program Execution This section describes those aspects of SPICE DL/I that apply to the operation of programs that use SPICE DL/I. It includes procedures that should be follow ed w hen certain error situations are encountered. This section consists of the follow ing topics: • • • • • • Application PSB Registration on page 96 Application Program Start on page 97 Application Program Restart on page 97 Application Program Rerun on page 99 SPICE GSAM Dataset Recovery/Restart on page 100 Interrupting Application Program Execution on page 104 Application PSB Registration For each program that executes under its control SPICE requires a PSB entry in the SPICE Restart Database. Should PSBs not registered in the SPICE database execute under SPICE, they w ill be registered automatically. Alternatively the SPICE operator facilities may be used explicitly to register a PSB in the SPICE Restart Database. SPICE Operator Subsystem PSBs can be registered in a SPICE Restart Database by selecting option INSERT from the PSB table panel. SPICE Utility Command The follow ing diagram defines the variant of the INIT command that can be used to register PSBs in a SPICE Restart Database: >>--- INIT --- DBDNAME --- ( --- name --- ) ------------------------------> >------------- PSBNAME --- ( --- name --- ) ------------------------------>< Utilit y Diagram 5.6: INIT command to regist er PSB in SPICE restart database Exam ple /*------------------------------------*/ /* EXAMPLE OF INIT COMMAND TO */ /* REGISTER PSB IN SPICE RESTART */ /* DATABASE */ /*------------------------------------*/ INIT DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) Utility Example 5.17: INIT PSBNAME... command 96 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Application Program Start The application JCL, built according to the guidelines in topic Application Program JCL on page 67, should be submitted to z/OS, follow ing standard procedures for IMS batch jobs. Determining Job Start Status The SPICE start status of a job can be determined by examination of the job entry as reported by the SPICE operator facilities. See topic Job Entry Reports on page 87 for details of how this report may be obtained. PSB SPIVP4CP JOB I63DIVBA I63DIVBA step G program SPIVCPUR entry created 2004.286 20:23:00.8 last change 0000.000 0:00:00.0 last start 2004.286 21:20:35.4 last restart 0000.000 0:00:00.0 last stop 2004.286 21:20:38.6 last commit 2004.286 21:20:38.6 identifier PPUR0008 Statistics: since job start commit points issued by program 9 commit points issued to DBMS 9 number database entries updated seconds elapsed since last start/restart 9 9 25 4 Report Example 5.18: Report of running SPICE jobs ACTIVE last start, last stop Absence of this text indicates that SPICE is aw aiting a normal start of the job. When present, this text indicates that either the specified job is executing or that it has failed and restart is required. SPICE w ill perform restart processing the next time the job executes the program. If the last execution of the program for this job ran successfully to completion, stop time w ill succeed start time. Application Program Restart The follow ing steps must be performed, to restart a restartable SPICE DL/I application program, after application or system failure: 1) Restore the application databases to their state at the time of the last successful checkpoint preceding the failure. When the program is run as a BMP, this is performed automatically by IMS. Note: If a problem arises w ith a SPICE GSAM file that requires that the file be recreated or re-allocated, the procedures detailed in item SPICE GSAM File Recovery/Restart must be followed. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 97 2) Resubmit the failed application job step. No modification is required to the step JCL. SPICE w ill issue a SPI0112I message upon restart. Determining Job Restart Status The SPICE restart status of a job can be determined by examination of the job entry using the SPICE operator facilities. SPICE Operator Subsystem Display the SPICE operator subsystem job table panel. Jobs that are executing or aw aiting restart are flagged as “ACTIVE” in the column headed “Status”. SPICE Utility Com m and See topic Job Entry Reports on page 87 for details of how this report may be obtained using the SPICE utility program. LIST DBD(SPICHSAM) PGM(ALL) JOB(ALL) PSB SPIDBPSB JOB SPICEUTI PSB SPIVP4CP JOB JOB SPICEJOB SPICEJOC ACTIVE Utility Example 5.19: Report of active SPICE jobs ACTIVE 98 This text, w hen present, indicates that the specified job is either executing or has failed and restart is required. SPICE w ill perform restart processing the next time the job executes the program. Absence of this text indicates that SPICE w ill not restart the program w hen the job is next executed. SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Application Program Rerun After an application or system failure, restartable SPICE DL/I programs w ill normally be restarted from their last checkpoint (otherw ise they w ould not have been so designed!). How ever, it is sometimes necessary, typically after a severe application logic failure, to rerun the job. For example, an application may have w ritten corrupt entries into application databases, and committed them w ith subsequent checkpoints. The extent of the corruption may be such that it is impractical to repair the databases, before restarting the program from the restart checkpoint. SPICE DL/I application program rerun is more complicated than restart because it is necessary to recover the application databases, and associated files, to their states w hen the job started its execution. The follow ing steps must be performed, to rerun a restartable SPICE DL/I application program: 1) Recover all the databases, except the SPICE Restart Database, to their state at the start of the program. 2) Recover all updated non-IMS datasets to their state at the start of the program. 3) Use the SPICE operator facilities to alter the status of the failed restartable SPICE DL/I job to allow the program to be rerun. SPICE Operator Subsystem SPICE can be instructed to allow a job to rerun by selecting option RERUN against the required job from the job table panel. To reverse an incorrect RERUN selection, select option RESTART . SPICE Utility Com m and The follow ing diagram defines the variant of the CHANGE command that will instruct SPICE to allow a job to rerun. >>--- CHANGE --- DBDNAME --- ( --- name --- ) ----------------------------> >--------------- PSBNAME --- ( --- name --- ) ----------------------------> >--------------- JOBNAME --- ( --- name --- ) ----------------------------> >----------------.-- RERUN ----.------------------------------------------>< +-- RESTART --+ Utility Diagram 5.7: CHANGE command for allowing application jobstep rerun RERUN RES TART Allow the selected program to be rerun w ith the selected jobname. Reverse the effect of an earlier CHANGE ... RERUN command. Note: This command w ill fail if it is issued against a program/job that has completed successfully. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 99 Exam ples /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS THAT */ /* RESETS THE SPICE RESTART DATABASE */ /* 'RESTART' INDICATOR, AND ALLOWS */ /* THE PROGRAM JOBSTEP TO BE RERUN */ /*------------------------------------*/ /* /* /* /* CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* INSTRUCT SPICE NOT TO JOBNAME(ABC123) /* RESTART UPON NEXT RERUN /* EXECUTION */ */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) JOBNAME(ABC123) RESTART */ */ */ */ /* /* /* /* ONLY ISSUE THIS COMMAND TO 'UNDO' THE EFFECT OF AN EARLIER 'RERUN' COMMAND ISSUED IN ERROR Utility Example 5.20: CHANGE ... RERUN command 4) Resubmit the failed application job step. No modification is required to the step JCL. The restart status of the job can be determined from job entry reports produced from the SPICE utility program. Topic Application Program Restart on page 97 describes this process. SPICE GSAM Dataset Recovery/Restart Physical Corruption Updates to SPICE GSAM datasets are not recorded on any log. Unlike databases, forw ard recovery of SPICE GSAM output files is not available follow ing irrecoverable I/O errors. End of Extent/Volume Failure (e.g. B37 Abends) Problems can occur w ith a SPICE GSAM output file, that do not involve loss of data: running out of space on a volume, for instance. Typically, successful completion of the program requires that the dataset be moved to another volume. SPICE provides for this eventuality, w ith the utility REPRO command. WARNING It is most important that simple copy programs, such as IEBGENER, are not used to copy SPICE GSAM files whilst a restart is pending. Using them can result in application corruption. 100 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Utility Com m and The utility REPRO command is used to copy a SPICE GSAM file to another dataset, w ithout compromising restart. It creates a copy of a SPICE GSAM dataset, and updates the restart data for the job, to reflect the physical contents of the new file. This copy, but not the original file, may then be used in a successful restart of the program. This procedure is necessary because, at each checkpoint, SPICE w rites out all records of SPICE GSAM output files that are held in its buffers, even if the buffers are not full. The output dataset may contain blocks shorter than the defined blocksize. For SPICE restart to execute successfully the SPICE GSAM dataset must contain identical blocks to those w ritten before the failure. It is not possible, therefore, to recover an insufficiently large SPICE GSAM output dataset simply by copying it to a larger extent, as the short blocks w ould be consolidated into full size blocks. The follow ing diagram defines the REPRO command. >>--- REPRO --- DBDNAME --- ( --- name --- ) -----------------------------> >-------------- PSBNAME --- ( --- name --- ) -----------------------------> >-------------- JOBNAME --- ( --- name --- ) -----------------------------> >-------------- INFILE ---- ( --- name --- ) -----------------------------> >-------------- OUTFILE --- ( --- name --- ) ----------------------------->< Utility Diagram 5.8: REPRO command for recovering SPICE SAM file PS BNAME JOBNAME INFILE OUTFILE The name of the PSB that the failed job w as executing. The name of the job that failed. The DD name of the file to be recovered. This must be the same DD name as was used in the failed job. The DD name of the file to be w ritten to. The command creates a copy of a SPICE GSAM file in use by a job aw aiting restart. Any records w ritten follow ing the restart checkpoint are truncated from the input file, and not w ritten to the output file. After the copy has completed, the SPICE Restart Database w ill reflect the restart position in the copy. The new file should then be used for the restart. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 101 Here is an example of the report contained in the command output: SPAN Integrated Checkpoint/Restart Environment, Release 3.1 page 0001 -------------------------------------------------------------------------------- REPRO DBD(SPICHSAM) PSBNAME(MYPGM) JOBNAME(MYJOB) INFILE(REPOUT) OUTFILE(REPOUTN) Repro Command Processing: DDname REPOUT (Input File) Restart Record Address 00001D00 00000050 (hex) DDname REPOUTN (Output File) Number records written 224 Restart Record Address Now 00001C00 00000230 (hex) SPI0310I COMMAND EXECUTED SUCCESSFULLY AT 2009.168 15:34:09.8 JCL Example 5.21: SPICE SAM REPRO command report example The output reports the follow ing: • For the input file, the address of the restart position as recorded in the restart database at the last successful checkpoint. • For the ouput file, the number of records w ritten to it and the address of the restart position, w hich replaces the value in the restart entry. After the copy has completed, the SPICE Restart Database w ill reflect the required restart position in the copy. The new file should then be used for the restart. Note the follow ing considerations: • • • • • • The job must be aw aiting restart. The utility program must run under a different job name from that specified in the command. The input file must have been processed by the specified job as a SPICE GSAM output file, using the DD name specified in the command. The output file must be record compatible w ith the input file. They must be of the same record type and the maximum record length of the output file must not be less than that of the input. The output file can reside on a different unit type, and the blocksize can be different. The file output by the command must be used in any subsequent restart of the job. If no SPICE file w ith the specified INFILE DD name w as open at the time of the restart checkpoint, the command will fail w ith message SPI0456. This message is also issued w hen the command fails because the user misspells the DD name. It is possible to check w hich files w ere open at the time of the restart checkpoint, by examining the dump format report of the job. See section Job Entry Reports on page 87 for further details. The follow ing procedure is suggested for use follow ing SPICE GSAM output file failure, an X37 Abend for instance: 1) Rename the failed file. This w ill protect against the possibility of attempting to restart the job w ith the failed file. 2) Execute the SPICE utility program to issue the REPRO command to copy the failed SPICE GSAM file to a new copy. The SPICE utility REPRO command places no restrictions on the device type or blocksize of the new data set. 3) If successful, rename the new file, to the original name 4) Restart the program, using the same JCL. 102 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Exam ple //JOBCARD JOB (ACCT),USER.NAME,CLASS=A,NOTIFY=USER,MSGCLASS=A //* //* DOC: THIS JOB RECOVERS A SPICE SAM OUTPUT FILE //* //BEFORE EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * ALTER SPICE.SPI31IVP.SE1PRINT.SSAMFB NEWNAME(SPICE.SPI31IVP.SE1PRINT.SSAMFB.X37) /* //REPRO EXEC IMSBATCH,MBR=SPIUTI00,PSB=SPIDCPSB, // IMSID=IVP1,COND=(0,NE) //STEPLIB DD // DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SPIUDUMP DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * LIST DBD(SPICHSAM) PSB(MYPGM) JOB(MYJOB) + FORMAT DUMP /* OPTIONAL */ REPRO DBD(SPICHSAM) PSB(MYPGM) JOB(MYJOB) + INFILE(SE1PRINT) OUTFILE(SE1PRI99) LIST DBD(SPICHSAM) PSB(MYPGM) JOB(MYJOB) + FORMAT DUMP /* OPTIONAL */ /* //SE1PRINT DD DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB.X37,DISP=SHR //SE1PRI99 DD DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB.NEW, // DISP=(NEW,CATLG), // UNIT=3380,VOL=SER=SPISYV, // SPACE=(CYL,(5,2)), /* FOR DISK */ // DCB=(RECFM=FB,LRECL=80,BLKSIZE=8000) //* //AFTER EXEC PGM=IDCAMS,COND=(0,NE) //SYSPRINT DD SYSOUT=* //SYSIN DD * ALTER SPICE.SPI31IVP.SE1PRINT.SSAMFB.NEW NEWNAME(SPICE.SPI31IVP.SE1PRINT.SSAMFB) /* // JCL Example 5.22: SPICE SAM output file recovery IMS procedure UNIT RECFM LRECL BLKS IZE The IMS procedure should include an allocation of the IMS DBD library, assigned to DD name IMS. The device type of the output file need not be the same as that of the input file. The record format of the output file must be the same as that of the input file. The record length of the output file must be the same as that of the input file. The blocksize need not be the same. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 103 Interrupting Application Program Execution SPICE includes a facility for interrupting the execution of SPICE application programs. This facility can be used to terminate quickly all executing SPICE DL/I applications, in order to allow IMS to be shut down and restarted w ith the minimum of disruption to online users. SPICE applications can be suspended by use of the SPICE operator facilities. Each job w ill then ABEND, user code 4090, after its next checkpoint. Message SPI0101I w ill be issued. This minimizes the recovery activity required by IMS, before the job is restarted. The SPICE operator facilities are also used to allow execution of the job, or jobs, to resume. The jobs can then be restarted. If a job is executed before this command is issued, it will abend after the first successful checkpoint. SPICE Operator Subsystem Jobs can be interrupted by selecting option SUSPEND from the program or job table panels. Selecting SUSPEND against a program will suspend all jobs using that program. The jobs can be resumed by selecting option RELEASE. SPICE Utility Command The follow ing diagram defines the variants of the CHANGE command that do this: >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ----------------------------> +- ALL --+ >--------------- PSBNAME --- ( -.- name -.- ) ----------------------------> +- ALL --+ >--------------- JOBNAME --- ( -.- name -.- ) ----------------------------> +- ALL --+ >----------------.-- SUSPEND --.------------------------------------------>< +-- RELEASE --+ Utility Diagram 5.9: CHANGE command for interrupting application execution S US PEND RELEAS E Cause the selected PSBs and jobs to abend follow ing their next checkpoint. Allow the selected PSBs and jobs to restart. Exam ples 104 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS THAT */ /* INTERRUPT THE EXECUTION OF */ /* RUNNING SPICE APPLICATIONS */ /***** ****/ /***** USE THIS COMMAND WITH CARE ****/ /***** ****/ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* INTERRUPT A SPECIFIC JOBNAME(ABC123) /* JOB SUSPEND */ */ - CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* ALLOW THE PSB TO BE JOBNAME(ABC123) /* RESTARTED RELEASE /* */ */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(ALL) JOBNAME(ALL) SUSPEND /* THIS WILL CRASH ALL /* EXECUTING SPICE DL/I /* APPLICATION PROGRAMS ! */ */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(ALL) JOBNAME(ALL) RELEASE /* ALLOW ALL PSB'S TO /* BE RESTARTED */ */ - Utility Example 5.23: CHANGE ... SUSPEND command PSB Entry Report Specification The suspend status of PSB and job entries is show n by text indicators in the formatted reports of the SPICE operator facilities. See topic Job Entry Reports on page 87 for details of how this report may be obtained. These indicators are as follow s: PS B entry report: S US PENDED job entry report: S US PENDED Indicates that execution of this PSB under SPICE has been suspended. Absence of this text indicates that the PSB can execute. Note: An individual job entry for this program may itself be flagged SUSPENDED. Indicates that execution of the PSB in this job under SPICE has been suspended. Absence of this text indicates that this job can execute with the PSB. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 105 Controlling SPICE Features This section describes how certain of the principal facilities of SPICE should be configured and used. This section consists of the follow ing topics: • • • • • • • Default Value Processing on page 106 Checkpoint Suppression on page 107 Application Program Timeout on page 110 SPICE In-Flight Restart ™ on page 113 SPICE Services Test Facility on page 116 Checkpoint Braking on page 116 Application Program Termination on page 119 Default Value Processing By default, SPICE takes its control parameters for the following facilities from the default values entry in its restart database. • • • SPICE checkpoint suppression. SPICE application timeout. SPICE checkpoint braking. The user can opt to use different values for a specific PSB. SPICE Operator Subsystem Select the program/PSB entry edit panel (option EDIT against the PSB from the PSB table panel). PSBs can be selected to use the default values by selecting value YES for option 3 ( DEFAULTS) from this panel. To opt for values specific to the PSB, select value NO. SPICE Utility Command The follow ing diagram defines the variant of the CHANGE command that does this: >>--- CHANGE --- DBDNAME --- ( --- name --- ) ----------------------------> >--------------- PSBNAME --- ( --- name --- ) ----------------------------> >------------------- USEDEFAULTS --- ( -.- YES -.- ) --------------------->< +- NO --+ Ut ility Diagram 5.10: CHANGE command to select non-default values for a PSB 106 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Exam ples /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS TO */ /* CONTROL SPICE OPTIONS FOR */ /* COMMIT POINT SUPPRESSION, BRAKING */ /* AND APPLICATION TIMEOUT VIA */ /* DEFAULT VALUES. */ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* USE DEFAULT VALUES FOR USEDEFAULTS(YES) /* SPECIFIC PSB */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP5CP) USEDEFAULT(YES) /* USE VALUES SPECIFIC TO /* THE PSB */ */ - CHANGE DBDNAME(SPICHSAM) /* SETUP CONTROL SPECIFIC PSBNAME(SPIVP5CP) /* TO PSB COMMIT(TIME(30,300) UPDATES(5000,0)) TIMEOUT(ABEND TIME(300,0) UPDATES(32000,0)) BRAKING(TIME(0,0) */ */ - Utility Example 5.24: CHANGE PSBNAME...USEDEFAULT S command PSB Entry Report Specification The status of this option is show n by text indicators in the formatted PSB entry report of the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. The indicator is: (DEFAULT VALUES ) When the default values entry parameters are to be used this indicator is found against the Check point Suppression, Application Timeout and Check point Brak ing sections of the report. Absence of this text indicates that the parameters are taken from the specific PSB entry. 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 on a IMS system. By diminishing the responsibility of application programs for checkpoint frequency, it can also simplify application design. SPICE monitors the numbers of updated database entries and time elapsed since the previous IMS checkpoint. SPICE also intercepts checkpoint requests. When appropriate, SPICE can suppress unnecessary checkpoints, by returning control to the application. The suppressed checkpoints are not passed to IMS. SPICE checkpoint suppression is controlled by the SPICE operator facilities. The parameters controlling the feature are stored in the SPICE Restart Database. Separate values are maintained for the IMS BMP and batch environments. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 107 SPICE Operator Subsystem To alter the parameters that control checkpoint suppression, first select the checkpoint control options panel: PSB Entry Select the program/PSB entry edit panel (option EDIT against the PSB from the Program/PSB table panel). Select option 4 ( COMMIT) from this panel. If this option is not displayed, SPICE is using the default values entry for its processing. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing PSBs. Default Values Entry Select option EDIT against the database from the database table panel. Select option 1 (COMMIT) from the database default entry edit panel. To alter the checkpoint suppression parameters, change the displayed values and select option 1 ( COMMIT). SPICE Utility Command The follow ing diagram defines the variant of the CHANGE command that is used to alter the checkpoint suppression parameters: >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ----------------------------> +- ALL --+ >------------.-- DEFAULTS ----------------------.-------------------------> +-- PSBNAME -- ( --- name --- ) --+ >--------------- COMMIT --- ( -- TIME ---- ( - value - , - value - ) -----> >------------------------------- UPDATES - ( - value - , - value - ) - ) ->< Utility Diagram 5.11: CHANGE command to control checkpoint suppression PS BNAME/DEFAULTS TIME UPDATES 108 Controls w hether the command should alter a specific PSB entry or the default values entry of the SPICE Restart Database. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing PSBs. Specifies the maximum elapsed interval, in seconds, that SPICE should monitor before passing a subsequent checkpoint request to IMS. The first value is used w hen the PSB is used by a BMP, the second w hen it is used by an IMS batch program. Values of 0 disable SPICE checkpoint suppression. Specifies the maximum number of database table row s that SPICE should monitor before passing a subsequent checkpoint request to IMS. The first value is used w hen the PSB is used by a BMP, the second w hen it is used by an IMS batch program. Values of 0 disable SPICE checkpoint suppression. SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Exam ples /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS FOR */ /* COMMIT POINT SUPPRESSION */ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) DEFAULTS COMMIT(TIME(30) UPDATES(1000) ) /* INTRODUCE COMMIT POINT /* SUPPRESSION FOR ALL /* DEFAULT VALUE PSB'S */ */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* INTRODUCE COMMIT POINT */ COMMIT(TIME(120) /* SUPPRESSION FOR SPECIFIC*/ UPDATES(250)) /* PSB, BY UPDATES */ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP5CP) /* INTRODUCE COMMIT POINT */ COMMIT(TIME(15) /* SUPPRESSION FOR SPECIFIC*/ UPDATES(32000)) /* PSB, BY TIME */ CHANGE DBDNAME(SPICHSAM) DEFAULTS COMMIT(TIME(0) UPDATES(0)) /* DISABLE COMMIT POINT /* SUPPRESSION FOR /* DEFAULT VALUE PSB'S CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP6CP) /* DISABLE BRAKING FOR COMMIT(TIME(0) /* SPECIFIC PSB UPDATES(0)) /* */ */ */ */ */ */ Utility Example 5.25: CHANGE command for controlling checkpoint suppression PSB Entry Report Specification The SPICE checkpoint suppression parameters can be found in the section headed Commit Point Suppression in the formatted report of the PSB entry produced by the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. PSB SPIVP4CP entry created 2004.286 restart entry length 2030 last change 0000.000 0:00:00.0 Commit Point Suppression (DEFAULT VALUES) thresholds: seconds updates DB2 & IMS BMP regions 30 1000 IMS BATCH regions 900 10000 Application Timeout (DEFAULT VALUES) WTO upon application timeout thresholds: seconds updates DB2 & IMS BMP regions 300 10000 IMS BATCH regions 0 0 Commit Point Braking (DEFAULT VALUES) wait period: seconds DB2 & IMS BMP regions 0 IMS BATCH regions 0 In-Flight Restart (DEFAULT VALUES) Terminate Out of Sync -Keep Restart loop detection limit restarts 5 Utility Example 5.1: Report of SPICE checkpoint suppression parameters Commit Point S uppression (DEFAULT VALUES ) This text, w hen present, indicates that the checkpoint suppression parameters w ere taken from the default values entry of the SPICE Restart Database tables. Absence of this text indicates that the parameters are specific to this program entry. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 109 thresholds: DB2 & IMS BMP regions This row contains the checkpoint suppression parameters IMS BATCH regions used by SPICE for this PSB, w hen it is run as an IMS BMP. This row contains the checkpoint suppression parameters used by SPICE for this PSB, w hen it is run in IMS batch. The first figure is the time threshold, in seconds, and the second is the update count threshold. If either of these values is zero, checkpoint suppression is disabled. Application Program Timeout SPICE application timeout anticipates problems arising from application programs that issue excessive uncommitted database updates. It can terminate such ill-conditioned programs, before other applications are affected. It can also detect programs that enter w ait states w hilst holding uncommitted database updates. Such programs, if left waiting for long enough, can create recovery complications for IMS. SPICE monitors the numbers of updated database entries and time elapsed since the previous checkpoint. SPICE intercepts database update commit statements. Application timeout by time occurs w hen a program exceeds an elapsed time threshold for uncommitted database updates. Application timeout by update count occurs w hen a program exceeds an elapsed database row update threshold w ithout issuing a checkpoint request. SPICE w ill then take one of the follow ing actions: • • • Issue a message to the z/OS operator. Issue a message to the z/OS operator asking w hether the program should be terminated abnormally or be allow ed to continue. Terminate the program abnormally. SPICE application timeout is controlled by the SPICE operator facilities. The parameters controlling the feature are stored in the SPICE Restart Database. Separate values are maintained for the IMS BMP and batch environments. SPICE Operator Subsystem To alter the parameters that control application timeout, first select the checkpoint control options panel: PSB Entry Select the program/PSB entry edit panel (option EDIT against the program from the PSB table panel). Select option 4 ( COMMIT) from this panel. If this option is not displayed, SPICE is using the default values entry for its processing. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing programs. Default Values Entry Select option EDIT against the database from the database table panel. Select option 1 (COMMIT) from the database default entry edit panel. To alter the checkpoint suppression parameters, change the displayed values and select option 2 ( TIMEOUT). 110 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Utility Command The follow ing diagram defines the variant of the CHANGE command that is used to alter the application timeout parameters: >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >-------------.- DEFAULTS ---------------------.----------------------------> +- PSBNAME --- ( --- name --- ) -+ >--------------- TIMEOUT -- ( -.- WTO ---.----------------------------------> +- WTOR --+ +- ABEND -+ >-------------------------------- TIME ----- ( - value - , - value - ) -----> >-------------------------------- UPDATES -- ( - value - , - value - ) - ) ->< Utility Diagram 5.12: CHANGE command to control application timeout PS BNAME/DEFAULTS WTO WTOR ABEND TIME UPDATES Controls whether the command should alter a specific PSB entry or the default values entry of the SPICE Restart Database. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing programs. Specifies that upon application timeout SPICE should issue message SPI0211W to the z/OS operator. Specifies that upon application timeout SPICE should issue message SPI0212W and request SPI0212A to the z/OS operator asking w hether the program should be terminated abnormally or be allow ed to continue. Specifies that upon application timeout SPICE should issue message SPI0213W to the z/OS operator and terminate the program abnormally. Specifies the interval, in seconds, that should elapse before SPICE instigates application timeout processing. The timing begins from the first database table update follow ing a IMS checkpoint. The first value is used w hen the PSB is used by a BMP, the second w hen it is used by an IMS batch program. Values of 0 disable SPICE application timeout by time. Note: This value is rounded up to the nearest minute. It should comfortably exceed the maximum interval for w hich IMS and/or z/OS are likely to suspend application program processing. Specifies the number of database row s that should occur before SPICE instigates application timeout processing. The count begins from the first database table update follow ing a IMS checkpoint. The first value is used w hen the PSB is used by a BMP, the second w hen it is used by an IMS batch program. Values of 0 disable SPICE application timeout by updates. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 111 Exam ples /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS FOR */ /* APPLICATION TIMEOUT */ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) DEFAULTS TIMEOUT(WTO TIME(300,0) UPDATES(10000,0)) /* /* /* /* INTRODUCE APPLICATION TIMEOUT FOR ALL DEFAULT VALUE PSB'S, OPERATOR NOTIFIED, NO ABEND */ */ */ */ CHANGE DBDNAME(SPICHSAM) DEFAULTS TIMEOUT(ABEND) /* CHANGE TO ABEND ACTION */ /* UPON APPLICATION TIMEOUT*/ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) TIMEOUT(WTOR TIME(600) UPDATES(5000)) /* /* /* /* INTRODUCE APPLICATION */ TIMEOUT FOR SPECIFIC */ PSB, OPERATOR TO */ DECIDE TO ABEND/CONTINUE*/ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* DISABLE APPLICATION TIMEOUT(TIME(0,0)) /* TIMEOUT BY TIME FOR /* SPECIFIC PSB */ */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP5CP) /* DISABLE APPLICATION TIMEOUT(UPDATES(0,0)) /* TIMEOUT BY UPDATES FOR /* SPECIFIC PSB */ */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* DISABLE APPLICATION TIMEOUT(TIME(0,0) /* TIMEOUT FOR SPECIFIC UPDATES(0,0)) /* PSB */ */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(ALL) TIMEOUT(ABEND) CHANGE DBDNAME(SPICHSAM) DEFAULTS TIMEOUT(ABEND) */ */ */ */ /* CHANGE TO APPLICATION /* TIMEOUT ACTION OF ABEND /* FOR ALL PSBS /* Utility Example 5.2: CHANGE command for controlling application timeout PSB Entry Report Specification The SPICE application timeout parameters can be found in the section headed Application Timeout in the formatted report of the PSB entry produced by the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. 112 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 PSB SPIVP4CP entry created 2004.286 restart entry length 2030 last change 0000.000 0:00:00.0 Commit Point Suppression (DEFAULT VALUES) thresholds: seconds updates DB2 & IMS BMP regions 30 1000 IMS BATCH regions 900 10000 Application Timeout (DEFAULT VALUES) WTO upon application timeout thresholds: seconds updates DB2 & IMS BMP regions 300 10000 IMS BATCH regions 0 0 Commit Point Braking (DEFAULT VALUES) wait period: seconds DB2 & IMS BMP regions 0 IMS BATCH regions 0 In-Flight Restart (DEFAULT VALUES) Terminate Out of Sync -Keep Restart loop detection limit restarts 5 Utility Example 5.3: Report of SPICE application timeout parameters Application Timeout (DEFAULT VALUES ) This text, w hen present, indicates that the application timeout parameters w ere taken from the default values entry of the SPICE Restart Database tables. Absence of this text indicates that the parameters are specific to this PSB entry. ACTION upon application timeout Indicates w hat action SPICE w ill take upon application timeout for this program. ACTION can take the value WTO, WTOR or ABEND. thresholds: DB2 & IMS BMP regions This row contains the application timeout thresholds used by IMS BATCH regions SPICE for this PSB w hen it is run as an IMS BMP. This row contains the application timeout thresholds used by SPICE for this PSB w hen it is run in IMS batch. The first figure is the time threshold, in seconds, and the second is the update count threshold. SPICE In-Flight Restart ™ SPICE In-Flight Restart™ is a facility that allow s application programs to continue processing successfully despite encountering certain failure conditions. For instance, contention betw een batch programs can result in the database management system backing out uncommitted updates, informing the program w ith an error code. Normally, the application w ould have no option at this point but to terminate. Programs that use SPICE, in contrast, have the option of performing a SPICE In-Flight Restart™, and continue their processing w ithout disruption. To cater for w hen the error condition persists, SPICE limits the number of In-Flight Restarts that a program can issue w ithout success, indicated by a successful checkpoint. SPICE In-Flight Restart™ is controlled by the SPICE operator facilities. The parameters controlling the feature are stored in the SPICE Restart Database. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 113 SPICE Operator Subsystem To alter the parameters that control application timeout, first select the checkpoint control options panel: PSB Entry Select the program/PSB entry edit panel (option EDIT against the PSB from the Program/PSB table panel). Select option 5 (REST CTL) from this panel. If this option is not displayed, SPICE is using the default values entry for its processing. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing programs. Default Values Entry Select option EDIT against the database from the database table panel. Select option 2 (RESTART) from the database default entry edit panel. To alter the SPICE In-Flight Restart™ parameter, change the displayed values and select option 1 (INFLIGHT). SPICE Utility Command The follow ing diagram defines the variant of the CHANGE command that is used to alter the application timeout parameters: >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >-------------.- DEFAULTS ---------------------.----------------------------> +- PSBNAME --- ( --- name --- ) -+ >--------------- RESTARTLIMIT -- ( --- value --- ) ------------------------->< Utility Diagram 5.13: CHANGE command to control application timeout PS BNAME/DEFAULTS RES TARTLIMIT Controls whether the command should alter a specific PSB entry or the default values entry of the SPICE Restart Database. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing programs. Specifies the maximum number of SPICE In-Flight Restarts that the program can issue w ithout a successful intervening checkpoint. Exam ples /*------------------------------------*/ /* EXAMPLE OF CHANGE COMMAND FOR */ /* SPICE IN-FLIGHT RESTART */ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) DEFAULTS - Utility Example 5.4: CHANGE command for controlling application timeout 114 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 PSB Entry Report Specification The SPICE application timeout parameters can be found in the section headed In-Flight Restart in the formatted report of the PSB entry produced by the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. PSB SPIVP4CP entry created 2004.286 restart entry length 2030 last change 0000.000 0:00:00.0 Commit Point Suppression (DEFAULT VALUES) thresholds: seconds updates DB2 & IMS BMP regions 30 1000 IMS BATCH regions 900 10000 Application Timeout (DEFAULT VALUES) WTO upon application timeout thresholds: seconds updates DB2 & IMS BMP regions 300 10000 IMS BATCH regions 0 0 Commit Point Braking (DEFAULT VALUES) wait period: seconds DB2 & IMS BMP regions 0 IMS BATCH regions 0 In-Flight Restart (DEFAULT VALUES) Terminate Out of Sync -Keep Restart loop detection limit restarts 5 Utility Example 5.5: Report of SPICE application timeout parameters In-Flight Restart (DEFAULT VALUES ) loop detection limit This text, w hen present, indicates that the application timeout parameters w ere taken from the default values entry of the SPICE Restart Database tables. Absence of this text indicates that the parameters are specific to this PSB entry. The maximum number of SPICE In-Flight Restarts that may be issued w ithout an intervening successful checkpoint. This section of the report is further explained in topic SPICE InFlight Restart ™ on page 113. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 115 SPICE Services Test Facility The SPICE services test facility allow s application programs to imbed special DL/I statements that facilitate the testing of restartable programs. 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 w hen the application issues a SPICE services statement. The follow ing JCL example illustrates the DD names used to control this facility: //JOBCARD JOB (ACCT),USER.NAME,CLASS=A,NOTIFY=USER,MSGCLASS=A //* //* DOC: THIS JOB EXECUTES THE SAMPLE APPLICATION. //* //PROCPURC EXEC IMSBATCH,MBR=SPIVCPUR,PSB=SPIVP4CP, // IMSID=IVP1 ... //TESTSDIE DD DUMMY /* MAKE THE PROGRAM ABEND */ ... // //JOBCARD JOB (ACCT),USER.NAME,CLASS=A,NOTIFY=USER,MSGCLASS=A //* //* DOC: THIS JOB EXECUTES THE SAMPLE APPLICATION. //* //PROCPURC EXEC IMSBATCH,MBR=SPIVCPUR,PSB=SPIVP4CP, // IMSID=IVP1 ... //TESTSERR DD DUMMY /* RAISE AN SQL ERROR */ ... // JCL Example 5.6: SPICE services test facility //TES TS DIE //TES TS ERR Presence of this DD name causes SPICE to terminate the program abnormally, w hen a SPICE services test facility statement specifying prefix “TESTS” is issued by the program. Presence of this DD name causes SPICE to return a non-zero SQLCODE, w hen a SPICE services test facility statement specifying prefix “TESTS” is issued by the program. Checkpoint Braking After each IMS checkpoint, SPICE can be configured to w ait for a user-specified interval. This is called SPICE checkpoint braking. It enables the user to control the rate at which a IMS batch program consumes IMS and system resources. SPICE checkpoint braking is controlled by the SPICE operator facilities. The parameters controlling the feature are stored in the SPICE Restart Database. Separate values are maintained for the IMS BMP and batch environments. 116 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Operator Subsystem To alter the parameters that control checkpoint braking, first select the checkpoint control options panel: PSB Entry Select the program/PSB entry edit panel (option EDIT against the PSB from the Program/PSB table panel). Select option 4 ( COMMIT) from this panel. If this option is not displayed, SPICE is using the default values entry for its processing. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing programs. Default Values Entry Select option Edit against the database from the database table panel. Select option 1 (COMMIT) from the database default entry edit panel. To alter the checkpoint braking parameters, change the displayed values and select option 3 ( BRAKING). SPICE Utility Command The follow ing diagram defines the variant of the CHANGE command that is used to alter the checkpoint braking parameters: >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >------------.-- DEFAULTS ----------------------.---------------------------> +-- PSBNAME --- ( --- name --- ) --+ >--------------- BRAKING -- ( --- TIME -- ( - value - , - value - ) --- ) -->< Utility Diagram 5.14: CHANGE command to control checkpoint braking PS BNAME/DEFAULTS TIME Controls whether the command should alter a specific PSB entry or the default values entry of the SPICE Restart Database. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing programs. Specifies the interval, in seconds, for w hich SPICE w ill suspend the application, follow ing a IMS checkpoint. The first value is used w hen the PSB is used by a BMP, the second w hen it is used by an IMS batch program. Values of 0 disable SPICE checkpoint braking. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 117 Exam ples /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS FOR */ /* COMMIT POINT BRAKING */ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) DEFAULTS BRAKING( TIME(15,0)) /* /* /* /* INTRODUCE 15 SECONDS BRAKING FOR ALL BMP'S WHOSE PSB'S USE DEFAULT VALUES */ */ */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) BRAKING(TIME(30,0)) /* INTRODUCE 30 SECONDS */ /* BRAKING FOR BMP'S USING */ /* SPECIFIC PSB */ CHANGE DBDNAME(SPICHSAM) DEFAULTS BRAKING(TIME(0,0)) /* DISABLE BRAKING FOR ALL */ /* PSB'S THAT USE */ /* DEFAULT VALUES */ CHANGE DBDNAME(SPICHSAM) PSBNAME(ALL) BRAKING(TIME(0,0)) /* DISABLE BRAKING FOR ALL */ /* PSB'S THAT DO NOT USE */ /* DEFAULT VALUES */ Utility Example 5.7: CHANGE command for controlling checkpoint braking PSB Entry Report Specification The SPICE checkpoint braking parameters can be found in the section headed Check point Brak ing in the formatted report of the PSB entry produced by the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. PSB SPIVP4CP entry created 91.079 15:54:15.0 restart entry length 2030 last change 91.095 17:40:34.7 Commit Point Suppression (DEFAULT VALUES) thresholds: seconds updates DB2 & IMS BMP regions 60 500 IMS BATCH regions 900 10000 Application Timeout (DEFAULT VALUES) WTO upon application timeout thresholds: seconds updates DB2 & IMS BMP regions 300 2000 IMS BATCH regions 0 0 Commit Point Braking (DEFAULT VALUES) wait period: seconds DB2 & IMS BMP regions 0 IMS BATCH regions 0 In-Flight Restart (DEFAULT VALUES) Terminate Out of Sync -Keep Restart loop detection limit restarts 5 Utility Example 5.8: Report of SPICE checkpoint braking parameters Checkpoint Braking (DEFAULT VALUES ) wait period: DB2 & IMS BMP regions 118 This text, w hen present, indicates that the checkpoint braking parameters w ere taken from the default values entry of the SPICE Restart Database tables. Absence of this text indicates that the parameters are specific to this PSB entry. This row contains the checkpoint braking interval, in seconds, used by SPICE for this PSB, w hen it is run as an IMS BMP. SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 IMS BATCH regions This row contains the checkpoint braking interval, in seconds, used by SPICE for this PSB, w hen it is run in IMS batch. Application Program Termination Normal application termination is intercepted by SPICE. This is usually interpreted as an indication by the program that its processing is complete, to which SPICE responds by marking as complete the restart data in its database before completing normal termination. The exception to this response occurs w hen the SPICE Restart Database is out of synchronization w ith the other restart resources, after processing a ‘ROLB’ request for instance. In this situation, SPICE requires a restart to restore synchronization. The default SPICE action here is to terminate normally but retain the restart data. SPICE includes an option to take the alternative action of SPICE terminating abnormally, also retaining the restart data. This out of synchronization termination option is controlled by the SPICE operator facilities. The parameters controlling the feature are stored in the SPICE Restart Database. SPICE Operator Subsystem To alter the parameters that control out of synchronization termination, first select the restart control options panel: PSB Entry Select the program/PSB entry edit panel (option EDIT against the PSB from the Program/PSB table panel). Select option 5 (REST CTL) from this panel. If this option is not displayed, SPICE is using the default values entry for its processing. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing programs. Default Values Entry Select option Edit against the database from the database table panel. Select option 2 (RESTART) from the database default entry edit panel. To alter the out of synchronization termination option, change the displayed value and select option 2 (OOSTERM). SPICE Utility Command The follow ing diagram defines the variant of the CHANGE command that is used to alter the out of synchronization option parameter: SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 119 >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >------------.-- DEFAULTS ----------------------.---------------------------> +-- PSBNAME --- ( --- name --- ) --+ >--------------- OUTOFSYNCTERM -- ( -.- KEEPRESTART -.- ) ------------------>< +- ABEND -------+ Utility Diagram 5.15: CHANGE command to control out of synchronization termination PS BNAME/DEFAULTS OUTOFS YNCTERM Controls w hether the command should alter a specific PSB entry or the default values entry of the SPICE Restart Database. Topic Default Value Processing on page 106 discusses how SPICE selects parameters for executing programs. Specifies the action SPICE should take follow ing out of synchronization termination. KEEPRESTART Retain the restart and terminate normally. ABEND Retain the restart and terminate abnormally. Exam ples /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS FOR */ /* OUT OF SYNC TERMINATION */ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) DEFAULTS OUTOFSYNCTERM(KEEPRESTART) CHANGE DBDNAME(SPICHSAM) PROGRAM(ABC123) OUTOFSYNCTERM(ABEND) - Utility Example 5.9: CHANGE command for controlling out of synchronization termination 120 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 PSB Entry Report Specification The SPICE out of synchronization termination parameter can be found in the entry labelled Terminate Out of Sync in the formatted report of the PSB entry produced by the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. PSB SPIVP4CP entry created 91.079 15:54:15.0 restart entry length 2030 last change Commit Point Suppression (DEFAULT VALUES) thresholds: DB2 & IMS BMP regions IMS BATCH regions Application Timeout (DEFAULT VALUES) WTO upon application timeout thresholds: DB2 & IMS BMP regions IMS BATCH regions Commit Point Braking (DEFAULT VALUES) wait period: DB2 & IMS BMP regions IMS BATCH regions In-Flight Restart Loop detection limit 91.095 17:40:34.7 seconds 60 900 updates 500 10000 seconds 300 0 updates 2000 0 seconds 0 0 Terminate Out of Sync -Keep Restart restarts 5 Utility Example 5.10: Report of SPICE out of sync termination control parameter Checkpoint Braking (DEFAULT VALUES ) Terminate Out of S ync: Keep Restart Abend This text, w hen present, indicates that the checkpoint braking parameters w ere taken from the default values entry of the SPICE Restart Database tables. Absence of this text indicates that the parameters are specific to this PSB entry. Retain restart data and terminate normally. Retain restart data and terminate abnormally. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 121 Other Facilities This section describes how to make use of those facilities not covered in other sections of this chapter. This section consists of the follow ing topics: • • • • • SPICE DL/I Restart Database Initialization on page 122 Disabling SPICE Restart on page 123 Restart Database Maintenance on page 124 SPICE MSDB Restart Database Repair on page 125 SPICE Operator Facilities Diagnostic Options on page 126 SPICE DL/I Restart Database Initialization The creation of DL/I SPICE Restart Databases is described in topic IMS Restart Database Creation on page 56. Before a SPICE Restart Database may be used, it must be initialized. SPICE Operator Subsystem To initialize the database select option INITIALIZE against the database from the database table panel. SPICE Utility Command A variant of the INIT command of the SPICE utility program is used for this. The follow ing diagram defines the command: >>--- INIT --- DBDNAME --- ( --- name --- ) --------------------------------> >------------- DEFAULTS ----------------------------------------------------> >----------------- SEGLEN --- ( -- value -- ) ------------------------------>< Utilit y Diagram 5.16: INIT command to init ialize restart database S EGLEN 122 The length of the checkpoint segment in the database. Its value is found in the DBD source. For DL/I HDAM and DEDB SPICE Restart Database, it is the maximum length of segment SPIDCHK. For DL/I MSDB SPICE Restart Database, it is the length of segment SPIDMSDB. SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Exam ple /*------------------------------------*/ /* EXAMPLE OF INIT COMMAND TO */ /* INITIALIZE SPICE RESTART DATABASE */ /*------------------------------------*/ INIT DBDNAME(SPICHSAM) DEFAULTS SEGLEN(2030) Utilit y Example 5.11: INIT command to init ialize SPICE restart database Disabling SPICE Restart It has been found that, in the early stages of application testing, automatic restart can make testing more difficult. The nature of early problems w ith programs is such that restart from a checkpoint is usually not required. It is therefore recommended that applications under development run with SPICE restart control disabled, until the application code becomes reliable. SPICE restart control may be disabled by use of the SPICE operator facilities. SPICE w ill issue a w arning message w hen the program is run. SPICE Operator Subsystem To disable SPICE restart from the operator subsystem, first select option 4 ( COMMAND) from the master menu panel. The utility command described below may then be entered. SPICE Utility Command The follow ing variant of the CHANGE command selects this option: >>--- CHANGE --- DBDNAME --- ( --- name --- ) ------------------------------> >--------------- PSBNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >------------------- SPICERESTART -- ( -.- YES -.- ) ----------------------->< +- NO --+ Utility Diagram 5.17: CHANGE command for suppressing SPICE restart S PICERES TART(YES ) S PICERES TART(NO) SPICE will save the information required for restart in its restart database at each IMS checkpoint. The program may then be restarted after failure. This is the default. SPICE will not save the information required for restart at each IMS checkpoint. The program cannot then be restarted after failure. It is highly unlikely that this option w ill be selected in a non-testing environment. SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 123 Exam ples /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS TO */ /* DISABLE AND ENABLE SPICE */ /* CONTROLLED RESTART */ /***** ****/ /***** USE THIS COMMAND WITH CARE ****/ /***** ****/ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* DISABLE SPICE RESTART SPICERESTART(NO) */ - CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* ENABLE SPICE RESTART SPICERESTART(YES) */ - Utility Example 5.12: CHANGE command for disabling SPICE restart PSB Entry Report Specification The status of this option is show n by a text indicator in the formatted PSB entry report of the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. The indicator is as follow s: RES TART DIS ABLED Indicates that SPICE restart is disabled for this PSB. It is highly unlikely that this option w ill be selected in a non-testing environment. Absence of this text, the default, indicates that SPICE restart is enabled. Restart Database Maintenance Over time it is likely that entries w ill accumulate in the SPICE Restart Database for PSBs and jobs that are no longer run. Such entries can be deleted from the tables w ith the SPICE operator facilities. By default, SPICE w ill not delete entries for PSBs and jobs that are active. It does, how ever, include options for deleting such entries. Incorrect use of this option can cause catastrophic application program failure. WARNING Great care should be taken with this command! SPICE Operator Subsystem To delete a job entry, select option DELETE against the job from the job table panel. To delete a PSB entry, select option DELETE against the PSB from the PSB table panel. 124 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Utility Command The follow ing diagram defines the DELETE command: >>--- DELETE --- DBDNAME --- ( --- name --- ) ------------------------------> >--------------- PSBNAME --- ( --- name --- ) ------------------------------> >-----------.------------------------------------.--------------------------> +--- JOBNAME --- ( -.- name -.- ) ---+ +- ALL --+ >----------------.-----------.---------------------------------------------->< +-- PURGE --+ Utility Diagram 5.18: DELET E command If this keyw ord is present, SPICE w ill delete all selected entries regardless of their restart status. Use with care ! PURGE Exam ples /*------------------------------------*/ /* EXAMPLES OF DELETE COMMANDS */ /* */ /***** ****/ /***** USE THIS COMMAND WITH CARE ****/ /***** ****/ /*------------------------------------*/ DELETE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* DELETE INACTIVE JOB JOBNAME(ABC123) /* */ */ DELETE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* DELETE INACTIVE JOBS JOBNAME(ALL) /* */ */ DELETE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* DELETE PSB ENTRY IF /* NO JOBS EXIST */ */ DELETE DBDNAME(SPICHSAM) PSBNAME(SPIVP5CP) /* DELETE JOB ENTRY, EVEN JOBNAME(ABC123) /* IF IT IS EXECUTING ! PURGE /* */ */ */ Utility Example 5.13: DELET E command SPICE MSDB Restart Database Repair SPICE DL/I includes a facility for marking individual entries in an IMS MSDB SPICE Restart Database as available for allocation by SPICE DL/I. This facility should only be used under guidance from the SPICE supplier. Incorrect use of this command can cause catastrophic application program failure. WARNING Great care should be taken with this option! SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 125 SPICE Operator Subsystem To use this facility from the operator subsystem, first select option 4 ( COMMAND) from the master menu panel. The utility command described below may then be entered. SPICE Utility Command The follow ing diagram defines the DELETE command w hen used against an entry in a MSDB SPICE Restart Database: >>--- DELETE --- DBDNAME ---- ( --- name --- ) -----------------------------> >--------------- MSDBINDEX -- ( --- value --- ) ---------------------------->< Utility Diagram 5.19: DELET E command against MSDB entry Identifies which entry in the database is to be flagged as available for allocation. SPICE w ill reject requests against an entry that is chained from another entry. This form of the DELETE command can lead to database corruption, and should be used w ith discretion. MS DBINDEX Exam ples /*------------------------------------*/ /* EXAMPLES OF DELETE COMMANDS */ /* AGAINST MSDB ENTRIES */ /* */ /***** ****/ /***** USE THIS COMMAND WITH CARE ****/ /***** ****/ /*------------------------------------*/ DELETE DBDNAME(SPICMSAM) MSDBINDEX(0023) /* FREE UP ACTIVE ENTRY /* (ONLY USE FOR REPAIR) */ */ Utility Example 5.14: DELET E command against MSDB restart database entry SPICE Operator Facilities Diagnostic Options When the SPICE operator facilities receive an invalid PCB status code in response to a DL/I statement to the restart database, SPICE normally issues a diagnostic message, and continues processing commands. A facility is available that causes SPICE instead to terminate abnormally. This facility is intended to be used only w hen requested by Span Softw are support staff. SPICE Operator Subsystem To control the SPICE operator facilities diagnostic options from the operator subsystem, first select option 4 ( COMMAND) from the master menu panel. The utility command described below may then be entered. 126 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Utility Command The follow ing diagram defines the command that provides this option, the SET command: >>--- SET --- DEBUG --- ( -.- NO --.- ) ------------------------------------> +- YES -+ Utility Diagram 5.20: SET diagnostic command The SPICE utility program w ill continue processing after receiving an invalid PCB status code. This is the default. The SPICE utility program w ill abend after receiving an invalid PCB status code. DEBUG(NO) DEBUG(YES ) Exam ples /*------------------------------------*/ /* EXAMPLES OF SET COMMANDS */ /*------------------------------------*/ SET DEBUG(ON) /* ABEND SPICE UPON BAD /* STATUS CODE FOR RESTART DB */ */ SET DEBUG(OFF) /* SPICE MESSAGE UPON BAD /* STATUS CODE FOR RESTART DB */ */ Utility Example 5.15: SET command diagnostic option SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 127 SPICE Utility Command Summary • • • • • • • CHANGE Command on page 128 DELETE Command on page 129 HELP Command on page 129 INIT Command on page 130 LIST Command on page 130 REPRO Command on page 130 SET Command on page 130 CHANGE Command >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >--------------- PSBNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >--------------- SPICERESTART -- ( -.- YES -.- ) ---------------------------> +- NO --+ >------------.-- SUSPEND --.------------------------------------------------> +-- RELEASE --+ >--------------- USEDEFAULTS --- ( -.- YES -.- ) ---------------------------> +- NO --+ >--------------- COMMIT --- ( --- TIME ----- ( - value - , - value - ) -----> >-------------------------------- UPDATES -- ( - value - , - value - ) - ) -> >--------------- TIMEOUT -- ( -.- WTO ---.----------------------------------> +- WTOR --+ +- ABEND -+ >-------------------------------- TIME ----- ( - value - , - value - ) -----> >-------------------------------- UPDATES -- ( - value - , - value - ) - ) -> >--------------- RESTARTLIMIT --- ( --- value --- ) ------------------------> >--------------- BRAKING -- ( --- TIME -- ( - value - , - value - ) --- ) --> >--------------- OUTOFSYNCTERM -- ( -.- KEEPRESTART -.- ) ------------------>< +- ABEND -------+ 128 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >--------------- DEFAULTS --------------------------------------------------> >--------------- COMMIT --- ( --- TIME ----- ( - value - , - value - ) -----> >-------------------------------- UPDATES -- ( - value - , - value - ) - ) -> >--------------- TIMEOUT -- ( -.- WTO ---.----------------------------------> +- WTOR --+ +- ABEND -+ >-------------------------------- TIME ----- ( - value - , - value - ) -----> >-------------------------------- UPDATES -- ( - value - , - value - ) - ) -> >--------------- RESTARTLIMIT --- ( --- value --- ) ------------------------> >--------------- BRAKING -- ( --- TIME -- ( - value - , - value - ) --- ) --> >--------------- OUTOFSYNCTERM -- ( -.- KEEPRESTART -.- ) ------------------>< +- ABEND -------+ >>--- CHANGE --- DBDNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >--------------- PSBNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >--------------- JOBNAME --- ( -.- name -.- ) ------------------------------> +- ALL --+ >----------------.-- RERUN ----.--------------------------------------------> +-- RESTART --+ >----------------.-- SUSPEND --.-------------------------------------------->< +-- RELEASE --+ DELETE Command >>--- DELETE --- DBDNAME --- ( --- name --- ) ------------------------------> >--------------- PSBNAME --- ( --- name --- ) ------------------------------> >-----------.------------------------------------.--------------------------> +--- JOBNAME --- ( -.- name -.- ) ---+ +- ALL --+ >----------------.-----------.---------------------------------------------->< +-- PURGE --+ HELP Command >>--- HELP ---.------------.------------------------------------------------>< +-- CHANGE --+ +-- DELETE --+ +-- HELP ----+ +-- INIT ----+ +-- LIST ----+ +-- REPRO ---+ +-- SET -----+ SPICE DL/I™ Operation 18 June 2009 © 1993,2009 Span Software Consultants Limited 129 INIT Command >>--- INIT --- DBDNAME --- ( --- name --- ) --------------------------------> >------------- DEFAULTS ----------------------------------------------------> >----------------- SEGLEN --- ( -- value -- ) ------------------------------>< >>--- INIT --- DBDNAME --- ( --- name --- ) --------------------------------> >------------- PSBNAME --- ( --- name --- ) -------------------------------->< LIST Command >>--- LIST --- DBDNAME --- ( -.- name -.- ) --------------------------------> +- ALL --+ >----------.-- DEFAULTS ---------------------.------------------------------> +-- PSBNAME --- ( -.- name -.- ) -+ +- ALL -+ >----------.---------------------------------.------------------------------> +-- JOBNAME --- ( -+- name -+- ) -+ +- ALL -+ >--------------+------------+--+------------+--+----------+----------------->< +-- ACTIVE --+ +-- FORMAT --+ +-- DUMP --+ REPRO Command >>--- REPRO --- DBDNAME --- ( --- name --- ) -------------------------------> >-------------- PSBNAME --- ( --- name --- ) -------------------------------> >-------------- JOBNAME --- ( --- name --- ) -------------------------------> >-------------- INFILE ---- ( --- name --- ) -------------------------------> >-------------- OUTFILE --- ( --- name --- ) ------------------------------->< SET Command >>--- SET --- DEBUG --- ( -+- NO --+- ) ------------------------------------> +- YES -+ 130 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Appendix A. Migrating from Previous Versions This appendix details of SPICE DL/I relevant to users of earlier versions of the SPICE products. • • • Release Compatibility on page 131 Deprecated SPICE Features on page 132 Discontinued SPICE Features on page 134 Release Compatibility • • • Database Compatibility on page 131 DL/I Interface Routine Compatibility on page 131 z/OS Language Environment (LE) User Exit on page 131 Database Compatibility SPICE DL/I uses the same database segment structure as SPICE DL/I 1.1. No conversion is required for SPICE application to use existing SPICE Restart Databases. DL/I Interface Routine Compatibility The DL/I language interface routine from SPICE DL/I 1.1 is compatible w ith SPICE DL/I 3.1. • Existing applications do not require link editing for SPICE DL/I 3.1. z/OS Language Environment (LE) User Exit SPICE 3.1 introduces an implementation of the z/OS LE User Exit CEEBXITA. The exit enables SPICE to interface w ith applications in a z/OS LE conforming manner. SPAN recommend the follow ing: • Applications that do not use the SPICE LE Exit must be executed w ith the z/OS LE ‘TRAP(OFF,NOSPIE)’ option. • This ensures that SPICE failure processing is not bypassed by z/OS LE. • Before SPICE DL/I 3.1 has been fully deployed, customer application programs should be link-edited not to include the SPICE LE Exit, SPIXLEUX. Migrating from P revious Versions 18 June 2009 © 1993,2009 Span Software Consultants Limited 131 • • Programs including the SPICE LE User Exit w ill not execute successfully under earlier releases of SPICE. Once SPICE DL/I 3.1 has been deployed, customers should alter their application build procedures, to include the SPICE LE Exit in SPICE application link edits. Deprecated SPICE Features The follow ing features of earlier SPICE releases are supported under SPICE DL/I, but their use is discouraged. • • • • • FCHK Function Code on page 132 SPICE SAM Pseudo-PCBs on page 132 SPICE SAM Variable Length Record Support on page 132 SPICE Utility Commands on page 133 TERM Function Code on page 134 FCHK Function Code The FCHK function code w as used as an alternative to CHKP, that would alw ays result in an IMS checkpoint. It is replaced by a double checkpoint. SPICE SAM Pseudo-PCBs SPICE Application programs can define their ow n SPICE SAM PCBs, in w orking storage. Note, how ever, that SPICE DL/I also supports AIB control blocks, even w hen no GSAM PCB exists. This standard technique of IMS achieves the same objective as pseudo-PCBs. If users w ish to process GSAM files, not defined in the PSB, it is recommended that they process their requests against AIBs. SPICE SAM Variable Length Record Support Very early versions of SPICE supported sequential file variable length records differently from GSAM. They communicated the record length in a fullw ord prefix, the first halfw ord of w hich contained the length. To execute programs w ritten in this nonstandard manner required that local modifications be made to SPICE. SPICE DL/I includes the follow ing option for supporting such programs. SPICE Operator Subsystem To control variable length record processing from the operator subsystem, first select option 4 ( COMMAND) from the master menu panel. The utility command described below may then be entered. 132 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 SPICE Utility Command The follow ing variant of the CHANGE command controls this option: >>--- CHANGE --- DBDNAME --- ( --- name --- ) ------------------------------> >--------------- PSBNAME --- ( --- name --- ) ------------------------------> >------------------- SSAM --- ( -.- STANDARD -----.- ) --------------------->< +- NONSTANDARD --+ Utility Diagram A.1: CHANGE command for controlling variable record processing S S AM(NONS TANDARD) S S AM(S TANDARD) For programs that use this PSB, SPICE w ill communicate variable record length w ith a full w ord prefix, the length being contained in the first halfw ord. For programs that use this PSB, SPICE w ill communicate variable record length in the standard GSAM manner, w ith a half word prefix containing the length. This is the default. Exam ples /*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS TO */ /* CONTROL PROCESSING OF VARIABLE */ /* LENGTH RECORDS. */ /*------------------------------------*/ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* I.E. USE NON-STANDARD SSAM(NONSTANDARD) /* FULLWORD PREFIX */ */ CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) SSAM(STANDARD)) */ */ - /* I.E. USE GSAM STANDARD /* HALFWORD PREFIX Utility Example A.1: CHANGE command for controlling variable record length processing PSB Entry Report Specification The status of this option is show n by a text indicator in the formatted PSB entry report of the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. The indicator is as follow s: NONS TANDARD S S AM Indicates that SPICE w ill communicate variable record length w ith a non-standard fullw ord prefix, for programs that use this PSB. Absence of this text indicates that SPICE w ill conform to the GSAM standard. SPICE Utility Commands SPICE 3.1 supports all previous dialects of the SPICE Utility Program command syntax. Migrating from P revious Versions 18 June 2009 © 1993,2009 Span Software Consultants Limited 133 TERM Function Code Early versions of SPICE required the program to issue a TERM request, immediately before termination. It is no longer required. Discontinued SPICE Features The follow ing features of earlier SPICE releases are not supported under SPICE DL/I. • • • Executing the SPICE Utility Program as an IMS Transaction on page 134 Restart Under Different Jobname on page 134 IMS Checkpointing using SYNC Function Code on page 135 Executing the SPICE Utility Program as an IMS Transaction Previous versions of SPICE allow ed the SPICE Utility Program to be executed as an IMS transaction. This is no longer supported. The SPICE TSO/ISPF Operator Subsystem is the recommended alternative. Restart Under Different Jobname Earlier version of SPICE did not require that the restart jobname was the same as that used for the normal start. This is no longer supported for the creation of SPICE Restart Database job entries. Existing database PSB entry dispositions w ill continue to be processed as before, and the command options for the feature are also supported. PSB Entry Report Specification The status of this option is show n by a text indicator in the formatted PSB entry report of the SPICE operator facilities. See topic PSB Entry Reports on page 84 for details of how this report may be obtained. The indicator is as follow s: ANY RES TART JOB NAME 134 Indicates that a program using this PSB may be restarted w ith a different job name. Absence of this text indicates that the same job name is required. SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 IMS Checkpointing using SYNC Function Code Earlier versions of SPICE included an option for selecting w hether the CHKP or SYNC function code would be used w hen SPICE issued an IMS checkpoint, w hen running as a BMP. The SYNC function code is now alw ays used for BMP checkpoints. Migrating from P revious Versions 18 June 2009 © 1993,2009 Span Software Consultants Limited 135 136 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 Glossary ACB. The Application Control Block, an IMS control block. ACBs are a refined form of the PSB and DBD control blocks, used by the IMS DBCTL control region. check point suppression. A SPICE technique for controlling the frequency of checkpoints from application program programs. AIB. The Application Interface Block, an IMS control block. IMS application programs can communicate DL/I requests using an AIB, instead of a PCB. column. The vertical component of an SQL database table. APAR. Authorized Program Analysis Report. A type of SMP/E sysmod. application timeout. A SPICE technique for detecting application programs that have failed to reach a commit point. back out. The process by w hich an application program's uncommitted database updates are abandoned. bind. The DB2 process w hereby DBRMs created by the DB2 precompiler are bound together w ith the database definitions to create an application plan. BMP. Batch Message Program. An IMS batch program that executes under the control of an IMS DBCTL. CAF. Call Attachment Facility. An interface program betw een an application program and the DB2 system. CASE. Computer Assisted Systems Engineering. CICS. Customer Information Control System. An IBM transaction manager. commit. The process whereby database updates are applied to databases. Until a commit point is reached, the DBMS will prevent other programs from accessing database elements against which uncommitted updates exist. commit point brak ing. A SPICE technique for reducing the rate at w hich an application program consumes resources. commit point suppression. A SPICE technique for controlling the frequency of commits from application program programs. CSI. SMP/E Consolidated Softw are Inventory. cursor. A named pointer into an SQL database table subset, defined by program specified selection criteria. database. For DB2 a group of SQL tables. For IMS, a set of segments, structured hierarchically. DB2. IBM Database 2. An IBM database management system. DBCTL. IMS DB Control region. check point. The process whereby database updates are applied to databases. Until a checkpoint is reached, the DBMS will prevent other programs from accessing database elements against which uncommitted updates exist. DBD. The Database Definition, an IMS control block. Each IMS database is defined to IMS w ith a DBD. check point brak ing. A SPICE technique for reducing the rate at w hich an application program consumes resources. DBRM. Database Request Module. An object created by the DB2 precompiler. DBMS. Database Management System, e.g. DB2 or IMS. Glossary 18 June 2009 © 1993,2009 Span Software Consultants Limited 137 DBRMs are bound together to create an application plan. application programs can access sequential files with DL/I requests. DD name. The label assigned to a z/OS JCL DD statement. HDAM. Hierarchical Direct Access Method, a type of IMS DL/I database. DD statement. An z/OS JCL dataset definition statement. hexadecimal dump. A report of the contents of an area of storage, presented in hexadecimal digits (0-9,A-F). deadlock . The name given to the situation w hen two application programs issue irreconcilable database requests. DEDB. Data Entry Database, a type of IMS fast path database. DL/I. Data Language/One. The query language for IMS databases. DL/I database. A category of IMS database. IMS DL/I databases can be accessed by IMS batch, or by IMS application regions connected to an IMS DBCTL. DL/I interface. The subroutine that IMS applications use to submit DL/I requests. DLIB. SMP/E Distribution Library. Dynamic SQL. Access requests to SQL databases that are created w hilst an application program is being executed. fast path database. A category of IMS database. IMS fast path databases can only be accessed by IMS regions connected to an IMS DBCTL, e.g. BMPs or MPPs. forced check point. A SPICE technique for ensuring an immediate checkpoint, even if checkpoint suppression is active. forced commit point. A SPICE technique for ensuring an immediate commit point, even if commit point suppression is active. function code. The first parameter of each DL/I statement, that defines the type of request. HLI. High level Language Interface module. The module that conveys program requests to the DBMS. host structure. A structure of program variables referenced by an SQL statement. host variable. A program variable referenced by an SQL statement. IMS. Information Management System. An IBM database and transaction management system. IMS batch. An IMS batch program that executes independently from IMS DBCTL regions. It supports its ow n databases. IMS DB. IMS database management system, a component of IMS. IMS TM. IMS transaction management system, a component of IMS. in-flight restart. A SPICE technique that enables an application program to continue processing after deadlock or program initiated failure, by re-issuing its restart requests. INCLUDE members. A facility that allows a program to include text from a member of a separate library. ISPF. The Interactive System Productivity Facility program product. It provides services for supporting on-line panel and menu driven applications under the TSO/E program product. JCL. z/OS Job Control Language. GSAM. Generalized Sequential Access Method, the means by w hich IMS 138 JES. Job Entry System. The z/OS job management system. SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009 MPP. Message Processing Program. An interactive IMS transaction program that executes under the control of an IMS DBCTL. restart. Execution of an application program after a failure, w here only processing performed after the last commit point is repeated. MSDB. Main Storage Database, a type of IMS fast path database. Restart API. The SPICE restart application program interface. A component of SPICE SQL. The Restart API is used by application programs to request SPICE facilities. OS sequential files. z/OS disk or tape files, that are processed in physical sequence. pack age. A DB2 object that represents the database access requirements of a group of application modules. It is created by the DB2 utility BIND command from the DBRMs of the modules. A package and the plans that reference it can be independently compiled and bound. PCB. The Program Communication Block, an IMS control block. There is one PCB for each IMS resource an application program can access. plan. A DB2 object that represents the database access requirements of an application program. It is created by the DB2 utility BIND command from a combination of module DBRMs and references to packages whose modules it uses. precompiler. The DB2 utility program that converts the SQL statements in an application program into a form that can be processed by the language compiler. It also creates the DBRM for the module. PSB. The Program Specification Block, an IMS control block. Each IMS program is given the address of its PSB, w hich contains a list of PCBs. PTF. Program Temporary Fix. A type of SMP/E sysmod. reposition. The process of moving the current record pointer in a sequential file. rerun. Execution of an application program after a failure, w here all processing is repeated. restart database. The database w here SPICE keeps information relating to its restartable programs. rollback . The process by w hich an application program's uncommitted database updates are abandoned. row. The horizontal component of an SQL database table. segment. A record in an IMS database. SMP/E. System Modification Program/Extended. A component of z/OS that is used to install and maintain system softw are. SPICE_PAM. The table against which SPICE SQL programs request SPICE program area management facilities. SPICE_SAM. The table against which SPICE SQL programs request SPICE sequential file facilities. SPICE_SERVICES. The table against w hich SPICE SQL programs request SPICE services facilities. SQL. Structured Query Language. The query language for DB2 databases. SQLCA. SQL Communication Area. A control block that serves as interface betw een an application program and DB2. SQLCODE. A field in the SQLCA control block. SQLERRM. A field in the SQLCA control block. Glossary 18 June 2009 © 1993,2009 Span Software Consultants Limited 139 status code. A field in each PCB, that IMS uses to communicate error conditions. symbolic check point/restart. An IMS facility for implementing restartable application programs. sysmod. SMP/E System Modification. table. A component in an SQL database. Tables consist of columns and row s. TSO DSN. The DB2 TSO command processor. In particular, this program can attach DB2 application programs. TSO/E. Time Sharing Option/Extended. A component of z/OS. VARCHAR. Variable length character string. An SQL data type. VSAM. Virtual Storage Access System. z/OS job log. The report of a program's execution produced by z/OS. z/OS. An IBM operating system. 140 SPICE DL/I™ Product Reference Manual © 1993,2008 Span Software Consultants Limited 18 June 2009