SPICE DB2 & IMS Product Description - Span Software · operation of restartable batch application programs in the IMS environment. ... (CHKP & CCHK Function Codes) ... (OPEN Function

SPICES p a n I n t e g r a t e d C h e c k p o i n t / R e s t a r t E n v i r o n m e n t

SPICE DL/I™

Product Reference Manual

Release 3.1

SPI 09 14

Span Software Consultants Limited

Lit t le Moss, Peacock Lane

High Legh

Knutsford

Cheshire

WA16 6PL

UNIT ED KINGDOM

T elephone: +44 (0) 1565 832999

Fax: +44 (0) 1565 830653

email [email protected]

website httl://www.spansoftware.com

© Copyright 1993, 2009 Span Software Consultants Limited.

All rights reserved. No part of this publicat ion may be re-produced,

stored in a r etrieval system or t ransmit ted, in any form or by anymeans, electronic, mechanical, or otherwise, without the prior writ ten

consent of the publisher.

18 June 2009

mailto:[email protected]

http://www.spansoftware.com

ii SPICE DL/I™ Product Reference Manual© 1993,2008 Span Software Consultants Limited 18 June 2009

Preface

Abstract

SPICE is an acronym for Span Integrated Checkpoint/Restart Environment.

SPICE DL/I™ is a software product that simplifies the design, implementation and

operation of restartable batch application programs in the IMS environment.

This manual is the principal reference for SPICE DL/I. It documents the facilities

available, how they can be incorporated into application programs, and how those

programs should be operated.

Other SPICE Manuals

SPI 08 SPICE SQL™ Product Reference Manual

This manual is the principal reference for SPICE SQL, the companion SPICE product

for the DB2 environment.

SPI 10 SPICE SQL™ & SPICE DL/I™ Diagnostics Reference Manual

This manual is the reference for the messages and other diagnostic information issued by

the SPICE products.

SPI 14 SPICE SQL™ & SPICE DL/I™ Getting Started

This manual is the reference for the installation of the SPICE products.

Note:

SPICE, SPICE DL/I, SPICE SQL, SPICE Restart API and In-Flight Restart are

trademarks of Span Software Consultants Limited.

IBM, IMS, DB2, CICS, z/OS and OS/390 are trademarks of the International Business

Machines Corporation.

Contents iii18 June 2009 © 1993,2009 Span Software Consultants Limited

Contents

Chapter 1. Introduction to SPICE DL/I™. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Using This Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Restartable Application Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

SPICE DL/I. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

SPICE Program Area Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

SPICE Sequential File Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

SPICE Checkpoint Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

SPICE Automatic Restart Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

SPICE In-Flight Restart™. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

SPICE Application Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

SPICE Checkpoint Suppression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

SPICE Application Timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Operating SPICE and its Application Programs. . . . . . . . . . . . . . . . . . . . . . . . . . 7

SPICE DL/I and SPICE SQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 with Checkpoints 11

Batch Program with SPICE DL/I 12

Restartable Program Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Program Start 13

Program Restart 13

Program Rerun 14

SPICE DL/I Programming Facilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Introduction to SPICE DL/I Programming Facilities. . . . . . . . . . . . . . . . . . . . . 15

Program Area Management Facilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Sequential File Processing Facilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Record Length Processing 16

File Record Position Processing 16

Application Testing Facilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Checkpoint Facilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Checkpoint Suppression 17

Forced Checkpoint 17

Other Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

SPICE DL/I and DB2 17

SPICE DL/I and CICS 17

Program Design Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Checkpoint Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

SPICE Checkpoint Suppression 18

iv SPICE DL/I™ Product Reference Manual© 1993,2008 Span Software Consultants Limited 18 June 2009

Location of Checkpoint statements 18

Checkpoint Frequency 18

Forced Checkpoints 18

Post Checkpoint Processing 19

Restart Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Placement of XRST Statement 19

Selecting Program Data for Restart 19

Sequential File Programming Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . 20


Restart Considerations 20

Checkpoint Considerations 20

Opening and Closing GSAM Files 20

Program Area Management Considerations 21

Supported File Organizations 21

Application Error Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

SPICE Processing of Rollback Conditions 22

SPICE In-Flight Restart™ 23

Program Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Initial Testing 24

Restart Testing 24

Chapter 3. Application Programming with SPICE DL/I™. . . . . . . . . . . . . . . . . . . 25

SPICE DL/I Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

General Principles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

DL/I Statements using PCBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

DL/I Statements using AIBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Language Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

SPICE DL/I Programming Diagnostics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Program Preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

SPICE DL/I Statement Layout Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . 30

Checkpoint & Restart Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Restart Request (XRST Function Code). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Description 31

Notes 32

Examples 33

Checkpoint Request (CHKP & CCHK Function Codes). . . . . . . . . . . . . . . . . . 33

Description 34

Notes 35

Examples 36

SPICE DL/I Rollback Request (ROLB Function Code). . . . . . . . . . . . . . . . . . . 37

Description 37

Notes 38

Examples 38

In-Flight Restart Initialization Request (INIT Function Code). . . . . . . . . . . . . . 38

Description 38

Notes 39

Examples 39

Sequential File Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

SPICE DL/I GSAM PCBs & AIBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

GSAM PCB Layout 40

AIB Support 41

Contents v18 June 2009 © 1993,2009 Span Software Consultants Limited

SPICE DL/I Processing of File DD Name 42

SPICE DL/I GSAM File Record Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . 42


File Record Position Processing 42

GSAM File Open Request (OPEN Function Code). . . . . . . . . . . . . . . . . . . . . . 43

Description 43

Notes 43

Examples 43

GSAM File Sequential Read Request (GN Function Code). . . . . . . . . . . . . . . . . 44

Description 44

Notes 44

Examples 45

GSAM File Reposition & Read Request (GU Function Code). . . . . . . . . . . . . . . 45

Description 45

Examples 46

GSAM File Write Request (ISRT Function Code). . . . . . . . . . . . . . . . . . . . . . . 46

Description 46

Notes 47

Examples 47

GSAM File Close Request (CLSE Function Code). . . . . . . . . . . . . . . . . . . . . . 47

Description 47

Examples 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. . . . . . . . . . . . . . . . . . . . . . . . . . 52

Checkpoint & Restart Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

GSAM Sequential File Management Statements. . . . . . . . . . . . . . . . . . . . . . . . 53

SPICE Services Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 4. SPICE DL/I™ Application Administration. . . . . . . . . . . . . . . . . . . . . . 55

Restart Database Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

IMS SPICE Restart Database Naming Rules. . . . . . . . . . . . . . . . . . . . . . . . . . 55

IMS System Preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

IMS Restart Database Creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

HDAM Restart Database Creation 57

DEDB Restart Database Creation 58

MSDB Restart Database Creation 59

IMS PSB Preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

IMS Restart Database Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

SPICE Restart Database usage 60

Number of SPICE Restart Databases 60

SPICE Restart Database Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

SPICE Restart Database Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Deleting Inactive SPICE Restart Database Entries 61

SPICE MSDB Restart Database Repair 62

Application Program Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

vi SPICE DL/I™ Product Reference Manual© 1993,2008 Span Software Consultants Limited 18 June 2009

Application Program Compile and Link-Edit. . . . . . . . . . . . . . . . . . . . . . . . . . 63

z/OS Language Environment (LE) Considerations 64

Run Time Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

IMS Application PSB Preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Sequential Dataset Allocation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

SPICE GSAM output files 66

Application Program JCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

IMS BMP Execution of SPICE Application 67

IMS BMP Execution of SPICE SQL Application 67

IMS Batch Execution of SPICE Application 68

JCL Considerations 68

z/OS Language Environment (LE) Considerations 69

Chapter 5. SPICE DL/I™ Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Introduction to SPICE Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Background.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

SPICE TSO/ISPF Operator Subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

SPICE Utility Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

SPICE Operational Responsibilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Operations Personnel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

First Line Operations Personnel 73

Operations Support Personnel 73

Operations Planning Personnel 73

Development Personnel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Database Administration and Technical Support 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

SPICE Utility Program Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

IMS BMP Execution of SPICE Utility 79

IMS BMP Execution of SPICE Utility, attached to DB2 80

IMS Batch Execution of SPICE Utility 80

JCL Considerations 81

SPICE Utility Program Command Conventions. . . . . . . . . . . . . . . . . . . . . . . . 81

SPICE Utility Program Help Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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




Contents vii18 June 2009 © 1993,2009 Span Software Consultants Limited


Default Values Entry Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92





MSDB Restart Database Contents Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . 94



Report Contents 95

SPICE DL/I Application Program Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Application PSB Registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96



Application Program Start. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Determining Job Start Status 97

Application Program Restart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Determining Job Restart Status 98

Application Program Rerun. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

SPICE GSAM Dataset Recovery/Restart. . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Physical Corruption 100

End of Extent/Volume Failure (e.g. B37 Abends) 100

Interrupting Application Program Execution. . . . . . . . . . . . . . . . . . . . . . . . . . 104



PSB Entry Report Specification 105

Controlling SPICE Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Default Value Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106




Checkpoint Suppression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107




Application Program Timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110




SPICE In-Flight Restart ™.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113




SPICE Services Test Facility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Checkpoint Braking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116




Application Program Termination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119




viii SPICE DL/I™ Product Reference Manual© 1993,2008 Span Software Consultants Limited 18 June 2009

Other Facilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

SPICE DL/I Restart Database Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . . 122



Disabling SPICE Restart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123




Restart Database Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124



SPICE MSDB Restart Database Repair. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125



SPICE Operator Facilities Diagnostic Options. . . . . . . . . . . . . . . . . . . . . . . . . 126



SPICE Utility Command Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

CHANGE Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

DELETE Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

HELP Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

INIT Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

LIST Command.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

REPRO Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

SET Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Appendix A. Migrating from Previous Versions. . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Release Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Database Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

DL/I Interface Routine Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

z/OS Language Environment (LE) User Exit. . . . . . . . . . . . . . . . . . . . . . . . . . 131

Deprecated SPICE Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

FCHK Function Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

SPICE SAM Pseudo-PCBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

SPICE SAM Variable Length Record Support. . . . . . . . . . . . . . . . . . . . . . . . . 132




SPICE Utility Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

TERM Function Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Discontinued SPICE Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Executing the SPICE Utility Program as an IMS Transaction. . . . . . . . . . . . . . 134

Restart Under Different Jobname. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134


IMS Checkpointing using SYNC Function Code. . . . . . . . . . . . . . . . . . . . . . . 135

Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Introduct ion to SPICE DL/I™ 118 June 2009 © 1993,2009 Span Software Consultants Limited

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.

2 SPICE DL/I™ Product Reference Manual© 1993,2008 Span Software Consultants Limited 18 June 2009

Introduction

The explosion in the number of on-line application systems has not removed the need

for batch processing. Every industry can quote processes that are most efficiently

performed by programs that do not require direct supervision from a terminal. It is a

growing trend that commercial and competitive considerations dictate that such

processing be performed concurrently with the on-line systems. IMS applications can be

run in such a fashion only if they are restartable.

SPICE DL/I is a software package that complements the facilities of IBM's IMS system,

for batch application programs. It provides a complete environment for the

development, maintenance and operation of restartable IMS application programs.

Users of SPICE DL/I benefit from the following:

• Operational benefits

SPICE DL/I provides easy to use interactive facilities for controlling SPICE DL/I

programs. It provides fully automatic restart of failing application programs, simply

by re-submission of the job; no JCL changes are required. The same operational

technique can be applied to all application jobs using SPICE DL/I.

• Development cost savings

The SPICE DL/I programming facilities are simple to learn and use. SPICE DL/I

programs request restart facilities, including sequential file processing, by issuing

DL/I statements. Minimal training of programming staff is required.

SPICE DL/I includes powerful facilities for controlling application program

checkpoint processing. These facilities minimise the programmer's responsibility

for checkpoint frequency. This results in less complex programs. SPICE DL/I also

includes easy to use facilities for testing restartable application programs.

Senior development staff are released from the task of developing and maintaining

in-house facilities and procedures.

SPICE DL/I results in reduced development and maintenance costs.

• Application integrity

SPICE DL/I meets the highest standards of reliability and integrity. The nature and

timing of external failures will not compromise the ability of SPICE DL/I to restart

the application successfully.

SPICE DL/I was developed and is marketed by Span Software Consultants Limited.

Span Software has been providing software for IBM mainframes since 1976.

Furthermore, Span Software has over 10 years of experience in delivering and

maintaining software to support restartable applications.

Span Software is proud of its record in providing and maintaining its software

worldwide for z/OS users in leading companies from all industry sectors.


Restartable Application Programs

Many customers require that increasing numbers of their batch applications co-exist

with their on-line applications. The mechanics of Data Base Management Systems

require such application programs to be restartable.

The reader will have experienced the frustration that occurs when one is interrupted

from reading a book by a telephone call, only to discover upon return that the book has

fallen shut. It can take some time to find again one's place in the story. A prudent

reader makes intelligent use of a bookmark. In a similar way, restartable programs

anticipate the possibility of system failure, and are so written as to minimize the

difficulties that will arise when an interruption in processing occurs.

Restartable programs regularly store information defining their current position in both

program code and data, typically in databases. Following a failure, they use this data to

minimize the processing that has to be repeated. The eventual state of the databases is

unaffected by any interruptions that may occur.

Programs that are not restartable have to process again from the beginning, which will

often require the recovery of databases from backup copies. This can be a lengthy

process. Selecting which backup copies to use can be a complex task, and may be prone

to operator error. Furthermore, in the case of programs that update databases alongside

the on-line systems, this form of recovery may result in the loss of database updates

issued from on-line transactions. This recovery option may be unacceptable to business

management, in which case batch applications will have to be restartable.

Implementing restartable programs has previously lead to significant increases in costs,

arising in both development and operational areas. SPICE DL/I™ and SPICE SQL™

have been conceived to minimize these additional costs.


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 software product that facilitates the implementation and operation of

restartable IMS application programs. It enhances the standard facilities in IMS for

restartable programs, providing significant improvements in application programming

costs, operation reliability and ease of use. SPICE DL/I has its own IMS databases for

managing its restartable application programs.

SPICE DL/I has the following characteristics:

Application Program Interface

• Simple to use facilities, requested via standard interfaces.

• Minimal training requirements.

• Integration between IMS databases and OS sequential files.

Operating Interface

• Simple to use facilities, available from a TSO/ISPF menu system.

• Minimal training requirements.

• Integration with automated operator facilities.

• Fail-safe operational procedures.

SPICE Program Area Management

SPICE program area management allows an application program to inform SPICE as to

which of its data areas contain information that the program will require for successful

restart. Should the application program fail, it will retrieve this information during

restart processing, and restore the program's data areas to their contents at the time of the

last checkpoint prior to the failure.


SPICE Sequential File Management

SPICE DL/I includes facilities for the processing of sequential files. SPICE will

maintain positioning information, in its database. Should the application program fail,

SPICE will retrieve this information during restart processing, and automatically re-

position 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 following:

• Saves the contents of designated application program data areas.

• Saves re-positioning information for sequential files under its control.

• Requests a checkpoint from IMS, to commit the updates to the databases.

SPICE Automatic Restart Processing

SPICE automatically detects when an application program is restartable. The same set of

JCL can be used for starting, restarting and rerunning SPICE applications, without

change. When the program issues its restart request, SPICE will determine whether

restart is required. When the program executes after a previous failure, SPICE will

perform the following restart processing:

• Restore application program data areas upon application request.

• Re-position sequential files.

SPICE facilities are available to override the program restart, so that the program may be

rerun.

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 with other

application programs.

If two programs compete for the same database entries the situation can arise where a

deadlock occurs. When this happens the system will resolve the deadlock by discarding

the uncommitted updates of one of them. In certain circumstances the affected

application program is informed of this. An IMS PCB status code of “BC”, for instance,

indicates that all uncommitted database updates have been lost. The application program

can itself abandon uncommitted database updates by issuing an IMS ROLB statement. In

either situation, the non-database files and the program areas are both out of step with the

database contents. Without in-flight restart, the only sensible option available to an

application program is that of immediate termination.

SPICE In-Flight Restart allows the application program to continue and complete its

processing without interruption. SPICE will detect the situations described above, and

allow the application program to re-commence its processing from the previous


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, within SPICE

programs. These breakpoints are activated by special DD names in the program JCL.

When these DD names are absent, SPICE will ignore the breakpoints. By altering the

application JCL, the user can force the application to fail at the breakpoint. The user can

then remove the JCL changes, so as to test restart of the program.

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, without committing the database updates.

SPICE checkpoint suppression is fully under the control of the installation. The

parameters are stored in a IMS database. They can easily be modified, by use of the

SPICE operational interface, and require no modification to application program code or

JCL.

SPICE Application Timeout

SPICE application timeout anticipates problems arising from excessive uncommitted

database updates. It can terminate such ill-conditioned programs, before other

applications are effected.

SPICE monitors the number of database segments that have been updated since the

previous database checkpoint. It also monitors the time interval over which database

updates remain uncommitted. When appropriate, SPICE can intervene to control errant

programs.

SPICE application timeout is fully under the control of the installation. The parameters

are stored in a IMS database. They can easily be modified, by use of the SPICE

operational interface, and require no modification to application program code or JCL.


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 with the easy to use SPICE TSO/ISPF

operator subsystem.

SPICE DL/I and SPICE SQL

SPICE SQL™ is a software product that facilitates the implementation and operation of

restartable DB2 application programs. It extends DB2 to provide facilities appropriate to

restartable programs, namely management of program data and sequential files required

for restart, both synchronized with DB2 commit point processing. SPICE SQL has its

own DB2 database for managing its restartable application programs.

When both SPICE DL/I and SPICE SQL are installed, the following facilities are

available in the IMS environment:

i) SPICE will monitor both DL/I and SQL activity, and all its facilities will be

available, in-flight restart for instance.

ii) SPICE SQL programs may be run as BMPs; 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.


SPICE DL/I™ Applicat ion Programming Principles 918 June 2009 © 1993,2009 Span Software Consultants Limited

Chapter 2. SPICE DL/I™

Application Programming Principles

This chapter describes the facilities of SPICE DL/I that are available from application

programs, and how programs should be coded to make use of them.

It is divided into the following sections:

SPICE DL/I Restartable Program Organization on page 10

This section discusses the need for restartable programs and their structure.

SPICE DL/I Programming Facilities on page 15

This section serves as an introduction to SPICE DL/I Programming. It describes

SPICE DL/I and its relationships with IMS, the principles underlying DL/I requests

for SPICE DL/I facilities, and how SPICE DL/I responds to programming errors.

Program Design Considerations on page 18

The effect that the SPICE DL/I facilities have upon the design of SPICE DL/I

application programs is discussed in this section.


SPICE DL/I Restartable Program

Organization

This section explains the architecture of SPICE DL/I restartable programs.

It illustrates the design of SPICE DL/I restartable programs with a simple program.

Restartable Program Structure on page 10

Restartable Program Execution on page 13

Restartable Program Structure

Simple Batch Program

Consider the following Activity Diagram, which illustrates the structure of a typical

batch program.

Figure 2.1: Simple batch program

It begins by performing its initialization, which will consist primarily of setting up its

data in working storage. It might then position itself in its databases. It then proceeds to

perform some form of repetitive processing until some criteria are met, when it

terminates. It might, for instance, be processing data from a sequential file, in which

case it would enter termination processing at end of file.

If this program had to process and update large numbers of database segments, we might

experience problems from the large number of uncommitted database entries that the

program would hold. To overcome this problem we could decide to add some

checkpoints.


Batch Program with Checkpoints

Our program might then look like the following:

Figure 2.2: Batch program with checkpoints

Our program now issues checkpoints after processing each iteration of our processing

loop. Because IMS, by default, loses database position during checkpoint processing, we

have to reposition them after the checkpoint.

Our program can now execute without holding large numbers of uncommitted updates.

A problem might arise, however, should the program, or the system, fail during

execution. Our program may have updated, and committed, many database entries. It

may prove difficult, or even impossible, to determine which entries have been updated.

The conventional strategy with such programs is to recover all the database tables to their

state at the beginning of the job, before rerunning the program. This can be a lengthy

and complex task. Furthermore, our databases might have been shared with other

updating programs, the on-line network for instance. If so, the option to rerun may not

be open to us; recovering our databases would undo all updates made by other programs.

This may be unacceptable. We may then decide that our program should be restartable.


Batch Program with SPICE DL/I

If we use SPICE DL/I, our program would then look like the following:

Figure 2.3: Restartable batch program

We have determined those areas of the program required for restart, and issued DL/I

statements to declare them to SPICE DL/I. We have also separated our initialization

processing into two parts; that which is required once only, when the program first

executes, and that required each time we execute, be it start or restart. Upon restart, we

also skip the initial reposition of the databases and instead skip forward to the database

reposition that we perform after each checkpoint. Our program is now restartable.


Restartable Program Execution

We will now consider some execution scenarios, and walk through the processing that

the program we developed in the previous topic will perform.

Program Start

We begin by performing general initialization. We then request restart and declare the

program areas that we require for restart to SPICE DL/I. As this is the start of our

processing, SPICE DL/I will hold no restart data for us and will respond with a

checkpoint identifier of blanks. We will therefore have to initialize our restart data areas.

Typical tasks performed here include obtaining the date, setting up database key

variables, clearing totals, setting up check sums etc. This is a reasonable moment to

issue a checkpoint. SPICE DL/I will now save the initial values of the restart data areas

to its database. As we are not restarting, we will now position our databases before

entering our main processing loop.

At the end of each iteration of the program, we issue a checkpoint. SPICE DL/I will save

the then current contents of the restart program areas to its restart database. At the end of

each iteration of the program, we issue a checkpoint and reposition our databases.

If our program runs to completion, SPICE DL/I will note the successful termination of

the program. SPICE will return no restart data to a subsequent execution of the program.

Program Restart

We will suppose that a failure has occurred whilst our program was executing. Perhaps

our program terminated abnormally. Alternatively z/OS might have failed while we were

running.

We begin, as before, by performing general initialization. We then request restart and

declare the program areas that we require for restart to SPICE DL/I. SPICE DL/I will

recognise that this is a restart, and restore the restart data from the last successful

checkpoint, to our restart program areas. It will return a non-blank checkpoint identifier.

We must therefore skip that part of our program that performs restart data area

initialization. This is again a reasonable moment to issue a checkpoint. SPICE DL/I will

now save the current values of the restart data areas to its database.

As we are restarting, we will now skip forward to reposition our databases before

continuing our main processing loop. We will have included database reposition values

in our restart data. The databases will therefore be positioned at the same point as that

which would have been processed had the failure not occurred. Similarly other restart

data, such as totals, check sums etc. will be unaffected by the failure.

We can now continue processing, without the failure affecting the processing performed

by our program.


Program Rerun

The failure may arise because of a severe program error that has been writing (and

committing) incorrect updates to the application databases. Our databases may be in

such a state that the only practical option is to rerun the program. To do this we will

have to recover all application data to its state at the beginning of the program's

execution. We also have to inform SPICE DL/I that rerun is required. These procedures

are explained fully in Chapter 5. SPICE DL/I™ Operation on page 71. We can then

start the program again. SPICE will not restore any restart data from its restart tables.


SPICE DL/I Programming Facilities

This section describes the facilities that SPICE DL/I offers the application program. It

also contains a discussion of the relationship between SPICE DL/I and various

programming techniques and environments.

• Introduction to SPICE DL/I Programming Facilities on page 15

• Program Area Management Facilities on page 15

• Sequential File Processing Facilities on page 16

• Application Testing Facilities on page 16

• Checkpoint Facilities on page 17

• Other Considerations on page 17

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 with a DL/I statement, using the

DL/I function code CHKP. This statement indicates up to seven areas whose contents are

to be saved to the SPICE Restart Database.

When the program first executes, no data is restored in response to the XRST statement,

and no checkpoint identifier is returned. When the program is restarted after a failure,

SPICE DL/I restores the area contents as saved in the SPICE Restart Database, and

returns the identifier of the checkpoint.


Sequential File Processing Facilities

SPICE DL/I provides facilities for the processing of sequential files via SPICE DL/I

statements.

The application program processes sequential files with SPICE DL/I by issuing DL/I

statements against GSAM PCBs or AIBs. SPICE DL/I intercepts these statements and

performs the appropriate processing. When the program first executes, file I/O will start

from the beginning of the file. When the program restarts after a failure, SPICE DL/I re-

positions the file, so that file I/O will restart from the point of the last successful

checkpoint. In other words, file processing will be unaffected by the interruption.

Record Length Processing

Programs that process records of variable or undefined length may determine the lengths

of records read, and specify the lengths of those written.

File Record Position Processing

Programs are able to process file positions. They can save the current file position. At

some later time, they can re-position the file to that point.

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


A SPICE Services test statement is imbedded at a point in the program where the

programmer wishes to test a failure. The facility is controlled by DD statements in the

application JCL. These JCL statements, typically assigned to DUMMY, define what action

SPICE is to perform when the application issues a SPICE services test statement,

abnormally terminate for instance. When the controlling DD statement is removed, the

SQL statement will process successfully. It is thereby possible to design a suite of JCL

that tests thoroughly the restart logic of a program.


Checkpoint Facilities

Checkpoint Suppression

SPICE checkpoint suppression is a technique that SPICE employs to control the

frequency of application program IMS checkpoints. It can thereby reduce the load upon

a IMS system. By diminishing the responsibility of application programs for checkpoint

frequency, it can also simplify application design.

An facility is available for the program to determine whether a checkpoint was

suppressed. This allows the program to avoid unnecessary database re-positioning.

Forced Checkpoint

An application program can override SPICE checkpoint suppression, by issuing two

checkpoint requests without any intervening processing.

Other Considerations

SPICE DL/I and DB2

If the application programs are to issue DB2 SQL statements, the SPICE SQL™ product

should be installed.

SPICE DL/I and CICS

SPICE facilities are appropriate only to batch processing, and therefore are not available,

or meaningful, to CICS transactions. However, most application systems using CICS

have ancillary processes performed by batch jobs. SPICE is eminently suited to these

batch programs.


Program Design Considerations

Topics in this section discuss in more detail the facilities available to SPICE DL/I

restartable programs, and what effect they might have on the design and structure of

SPICE DL/I programs.

• Checkpoint Considerations on page 18

• Restart Considerations on page 19

• Sequential File Programming Considerations on page 20

• Application Error Processing on page 22

• Program Testing on page 24

Checkpoint Considerations

This topic discusses design considerations for SPICE DL/I restartable programs that are

associated with checkpoint processing.

SPICE Checkpoint Suppression


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


Further details of this feature may be found in topic Checkpoint Suppression on page 6.

Location of Checkpoint statements

DL/I checkpoint statements are best issued from key points in program logic, e.g. at the

end of loops or when the program enters a new phase. This makes the program restart

logic easier to understand, and write, than issuing checkpoints at fixed intervals in time,

or after rigid counts of update statements.

Checkpoint Frequency

It is better for SPICE applications to issue too many checkpoints, than too few. It is

suggested that application programs issue DL/I checkpoint statements at least every 100

database segment updates, or 10 elapsed seconds. Note that it is quite in order to issue

checkpoint statements more frequently than this. SPICE checkpoint suppression will

prevent a program's enthusiasm for checkpoints from overloading the IMS system.

Forced Checkpoints

An application program can override SPICE checkpoint suppression, and force a IMS

checkpoint, by issuing two DL/I checkpoint statements without any intervening

processing.

Forced checkpoints are rarely necessary. An example of such is a program that is about

to enter an extended period without issuing checkpoint requests (e.g. a long sort). It

would be undesirable to leave any database updates uncommitted over the period of the

processing. It would be appropriate to issue a double checkpoint here.


Post Checkpoint Processing

SPICE DL/I application programs should always reposition their databases after issuing

checkpoint requests with the CHKP function code. If they use the CCHK function code,

they can test the i/o area to determine whether it is necessary to reposition the databases.

Restart Considerations

This topic discusses design considerations for SPICE DL/I restartable programs that are

associated with the restart processing.

Placement of XRST Statement

The program areas declaration, using the XRST function code, should be placed very

early in the program’s processing. It will, typically, be the first DL/I statement in a

program.

Selecting Program Data for Restart

What areas of the program should an application include in the areas that it declares to

SPICE DL/I? It should include all data required to re-establish its processing upon

program restart. Other than that, broadly speaking, as little as possible. All the restart

data has to be written to the SPICE Restart Database; the more data, the more database

and IMS log I/O activity.

The following items of data should be considered:

• Data totals.

• Environment indicators, i.e. date and time of start of run.

• Check sums.

• Identification of which location in the program initiated the checkpoint.

• Database position key values.

• Sequential file buffers.

• Reasons why one might wish to consider checkpointing sequential file record

area are discussed in topic Sequential File Programming Considerations, on

page 20.


Sequential File Programming Considerations

This topic discusses those design considerations for SPICE DL/I restartable programs

that are associated with the processing of sequential files.


The program may need to process record lengths for a file with variable length or

undefined length records.

Variable Length Records

The binary record length is stored in a 2 byte prefix to the record.

Undefined Length Records

The length of undefined length records is communicated in a field in the PCB

Restart Considerations

When SPICE is restarted, sequential files that were open at the time of the last successful

checkpoint will be re-positioned automatically.

Checkpoint Considerations

When SPICE DL/I takes a checkpoint, it saves the current positions of all the open

GSAM files.

Opening and Closing GSAM Files

Programs that wish to explicitly open and/or close GSAM files, should always ensure

that a checkpoint is taken, before performing any further action against the file. Topic

Checkpoint Request (CHKP & CCHK Function Codes) on page 33 explains how this

should be done.

This is especially important when re-opening output files. This is performed typically to

empty a file before writing out further records. The following example illustrates why.

Consider the following processing scenario:

1) Write 1000 records to file OUTA.

2) Issue checkpoint.

3) Issue DL/I CLSE to request file close against OUTA.

4) Issue DL/I OPEN to request file open against OUTA.

5) Write 5 records to file OUTA.

6) Program or system failure.

7) Restart program, get failure when re-positioning OUTA.

Upon restart, when the program attempts to write to OUTA, SPICE will attempt to

reposition the file to the record following the last written before the restart

checkpoint. The restart checkpoint is at point 2). The physical end of file

however, will be after the records written at point 5). This will result in file

failure.

Forcing a checkpoint after point 3) avoids the restart failure.


Program Area Management Considerations

It is sometimes necessary to include the record buffer for a SPICE GSAM input file in

the program areas required for restart.

For example, consider an application that is driven by a file of transactions, stored in an

sequential file. The transactions are processed in batches, relating to a particular key for

example, before each checkpoint. The end of a batch is indicated by reading the first

record from the following batch. This situation presents difficulties upon program

restart. SPICE will reposition its files after the last record read. As the first record from

the next batch has been read, the DL/I GN to the GSAM file PCB would retrieve the

second record in the batch, thus causing the first to be missed. Three techniques are

suggested for handling this situation.

• The transaction file could be designed to include a batch trailer record, to indicate

positively the end of a batch. This technique is recommended when designing new

systems. However, it may not be possible to change the design of an existing

transaction file.

• Include the record buffer in the program's restart data areas. Thus, after restart from

a successful checkpoint, the first record of the next batch is presented in the record

buffer, without issuing a DL/L GN statement.

• Include the record search address (RSA) in the program's restart data areas. Each

DL/I GN statement should request the optional RSA value. After restart from a

successful checkpoint, the program can issue a GU, using the saved RSA, to re-

retrieve the record current at the time of the checkpoint.

Supported File Organizations

SPICE sequential file management supports the following file types, with full restart

support; SPICE will automatically reposition files of these types when the program is

restarted.

z/OS physical sequential datasets:

• any length record, fixed length, variable length and undefined length record formats.

The program can access and specify the record length, if required.

• disk or tape, single or multiple volume.

SPICE also processes the following file types, but without restart support. Upon restart;

SPICE will not reset their position to that at the time of the restart checkpoint. When

such files are used, SPICE will issue message SPI00112I to notify the user that restart re-

positioning is not available.

• JES input (“DD *”) and JES output (“SYSOUT”) files.

• TSO files (“DA(*)”).

• Concatenated input files.

• Members of partitioned data sets (PDS members).


Application Error ProcessingSPICE DL/I gives the maximum flexibility of options for application error processing,

without compromising program restart. The following items summarize the related

aspects of SPICE processing.

SPICE Processing of Rollback Conditions

SPICE recognises those PCB status codes that indicate that IMS was forced to abandon a

program’s uncommitted database updates, BC for instance. It also recognises explicit

rollback statements, using the DL/I ROLB function code.

These conditions result in loss of all database updates issued since the previous

checkpoint. The state of the restart program areas and SPICE sequential files will not

reflect the current contents of the databases. SPICE DL/I therefore suspends its

processing of checkpoints until a restart has been performed. Following a rollback of

database updates, SPICE allows the program to perform any of the following, whilst

retaining the restart data saved at the checkpoint preceding the rollback:

Application database DL/I statements This allows the program to insert entries to an

error database.

DL/I checkpoint statements This allows the program to commit any updates issued after

the rollback. SPICE will pass the DL/I checkpoint request

on to IMS, but not alter the contents of its restart database.

SPICE DL/I sequential file processing This allows the program to write error messages

to SPICE GSAM files.

DL/I rollback statements Unlikely, but the program can issue further DL/I ROLB

statements, if it considers them appropriate.

Normal termination This allows the program to terminate without an abend, yet

restart upon re-submission.

The pending restart is reactivated by one of the following actions:

Program termination After termination of the program, SPICE will resume its

standard processing: the next execution of the program will

be processed as a restart.

Restart request If the application program re-issues its XRST statement, SPICE

will perform restart processing and restore the contents of the

areas from its restart database tables. SPICE sequential files will

also be re-positioned. This form of restart is termed SPICE in-

flight restart™.

As can be seen above, SPICE DL/I presents few obstacles to application error

processing. SPICE DL/I does not prevent the program from updating its databases. As

restart is suspended, the program could create a situation that conflicts with the data in

the SPICE Restart Database tables. It is strongly recommended that enterprise data is not

altered during error processing. Databases should be used only as a means of recording

the error.


SPICE In-Flight Restart™

As noted in the previous item, SPICE DL/I includes a facility for performing restart

whilst 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 two ways. 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 between 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”.

Following the rolling back of uncommitted updates, the application program can regain

synchronization between the databases, program areas and SPICE GSAM files by re-

issuing 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 will be

automatically re-positioned to that point.

Use of SPICE In-Flight Restart requires that the program do the following:

• If the program wishes to receive “BC” status codes when deadlock occurs, it should

issue a DL/I statement to the I/O PCB using function code INIT, with 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 which 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 would be identical to that which

would have been performed had the program terminated abnormally and then been

restarted.

SPICE will limit the number of consecutive in-flight restarts, without an intervening

checkpoint. Should the limit be exceeded, SPICE will 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.


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 will 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

will 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 switch 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 without the failure. The

simplest technique is to cancel the program and then resubmit it. This may require the

cooperation of the operator, and would 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 which point the program should fail; just before a

checkpoint is a good choice. The action that SPICE DL/I will perform is dependent upon

which DD names are present in the job JCL. The following DD statements may be

included in the JCL to request the related action, where prefix is the value of the DD

name prefix specified in the test facility request:

//prefixDIE DD DUMMY The program will abnormally terminate.

//prefixERR DD DUMMY The program will 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 with one of the above DD names present.

The program job can then be rerun with the DD statement omitted, when it should restart

and run successfully to completion.

SPICE™ Applicat ion Programming with SPICE DL/I™ 2518 June 2009 © 1993,2009 Span Software Consultants Limited

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 DL/I Statements

This section describes the following 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 with checkpoint processing, notably XRST, CHKP and ROLB,

initiate additional processing by SPICE DL/I.

DL/I statements issued against GSAM PCBs or AIBs are processed directly by SPICE

DL/I. 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. Otherwise, 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.


DL/I Statements using PCBs

COBOLCALL 'CBLTDLI' USING function, pcb,

i/o area [,ssa1,...,ssa15].

PL/ICALL PLITDLI (parmcount, function, pcb,

i/o area [,ssa1,...,ssa15]);

PascalPASTDLI(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 LanguageCALL 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).


DL/I Statements using AIBs

COBOLCALL 'AIBTDLI' USING function, aib,

i/o area [,ssa1,...,ssa15].

PL/ICALL AIBTDLI (parmcount, function, aib,

i/o area [,ssa1,...,ssa15]);

PascalAIBTDLI(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 LanguageCALL 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 with 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).


Language Support

SPICE DL/I can be used within 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 following:

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 following 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, whose DBD name begins with the characters

SPICR.

Find further information on the preparation of SPICE programs in Chapter 4. SPICE

DL/I™ Application Administration on page 55.


SPICE DL/I Statement Layout Conventions

For the remainder of the manual, DL/I statement parameter list contents will 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 following alternatives:

• i/o pcb

• i/o aib

• i/o area len

• i/o area

• A number of occurrences of pairs of:

• area length

• area

Following each diagram will be a description of what each element represents.


Checkpoint & Restart Processing


• 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 with the DL/I restart statement.

The statement also declares those program areas whose contents are required for program

restart.

The parameter list to the DL/I statement contains the following elements. For a

description of this layout, see SPICE DL/I Statement Layout Conventions on page 30.


>-------------.------------------------------------.------------------>< | |

| .----------------------------. | | | | |


DL/I Diagram 3.4: SPICE DL/I restart statement (XRST )

DescriptionXRST

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.


area len


following area parameter.area

The name of an area in your program, whose 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, without 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 will start normally.

For a normal start, SPICE DL/I will 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 will 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 where they were 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, following a status code of “BC” or ROLB statement, for

instance. Further information may be found in topic SPICE In-Flight Restart™ on page

5.


Examples

01 FUNC-XRST PIC X(04) VALUE 'XRST'.01 MAX-PATH-LEN PIC 9(09) COMP VALUE 128.

01 IOAREA. 02 CHKP-ID PIC X(08). 02 FIELD-1 PIC 9(09) COMP.

02 FIELD-2 PIC X(68). 01 AREA-1-LEN PIC 9(09) COMP VALUE 32.

01 AREA-1 PIC X(32) VALUE SPACES. 01 AREA-2-LEN PIC 9(09) COMP VALUE 16. 01 AREA-2.

02 FIELD-1 PIC X(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 will 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 which areas within the program are

required for restart.



>>--- CHKP ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+

>--------------.------------------------------------.----------------->< | |

| .----------------------------. | | | | |


>>--- 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


DescriptionCHKP


“CHKP”. CCHK


“CCHK”. Use “CCHK” when 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





“IOPCB ”. The routine name “AIBTDLI” must be used.i/o area len


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, within the program's checkpoints, or between programs.

The following 4 bytes are used when 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


following area parameter.area

The name of an area in your program, whose 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 within the areas defined in the restart statement.


Notes

Before conveying a checkpoint to IMS, SPICE will save the following:

• 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 always take the value of blanks. As the program is unaware of

suppressed checkpoints, it should assume that database position has been lost, and

reposition its databases before proceeding.

For most programs the CHKP function code is entirely satisfactory. It is possible,

however, that the overhead of redundant database re-positioning becomes unacceptable.

To cater for this situation, SPICE DL/I introduces the CCHK function code. If function

code CCHK is used, the program will be informed, as follows:

• If the checkpoint is suppressed, a binary value of 4 will be returned in the 4 bytes

following 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, without any intervening processing.


Examples

01 FUNC-CHKP PIC X(04) VALUE 'CHKP'.01 MAX-PATH-LEN PIC 9(09) COMP VALUE 128.





01 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 funct ion 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 will reposition its databases after the checkpoint

statement.

01 FUNC-CCHK PIC X(04) VALUE 'CCHK'.01 MAX-PATH-LEN PIC 9(09) COMP VALUE 128.


02 FIELD-2 PIC X(68).01 AREA-1-LEN PIC 9(09) COMP VALUE 32.

01 AREA-1 PIC X(32) VALUE SPACES.01 AREA-2-LEN PIC 9(09) COMP VALUE 16.01 AREA-2.

02 FIELD-1 PIC X(16) VALUE SPACES....

LINKAGE SECTION.

01 IO-PCB.


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 funct ion 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 will examine field

FIELD-1 of IOAREA, to determine if its databases should be re-positioned.


01 FUNC-CHKP PIC X(04) VALUE 'CHKP'.01 MAX-PATH-LEN PIC 9(09) COMP VALUE 128.





01 IO-PCB.





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.



>>--- ROLB ---.--- i/o pcb ---.---.----------------.------------------>< +--- i/o aib ---+ +--- i/o area ---+

DL/I Diagram 3.6: Rollback uncommitted updates

DescriptionROLB


“ROLB”.i/o pcb





“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.


Notes

After the rollback statement, SPICE will allow the application program to restart. To

retain synchronization between the databases, program areas and SPICE GSAM files, the

program should reissue the restart statement. It will recover the contents of its program

areas to their state at the last successful checkpoint. The SPICE GSAM files will 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 abandonuncommitted updates

The example will 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 will then return a 'BC' status codes, in the event of a deadlock.



>>--- INIT ---.--- i/o pcb ---.--- i/o area -------------------------->< +--- i/o aib ---+

DL/I Diagram 3.7: DL/I init ializat ion (INIT )

DescriptionINIT


“INIT”.i/o pcb





“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”.


Notes

Following this statement, when 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 wish 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 PIC X(04) VALUE 'INIT'.01 STATUS-GROUPB PIC X(16) VALUE 'STATUS GROUPB'.

...LINKAGE SECTION.01 IO-PCB.


...PROCEDURE DIVISION.

ENTRY 'DLITCBL' USING IO-PCB, ......

CALL 'CBLTDLI' USING FUNC-INIT, IO-PCB, STATUS-GROUPB.

COBOL Example 3.6: DL/I init ializat ion statement (INIT )

The example instructs IMS to return a PCB status code of “BC”, when backout occurs

due to deadlock.


Sequential File Processing


• SPICE DL/I GSAM PCBs & AIBs on page 40

• SPICE DL/I GSAM File Record Processing on page 42

• GSAM File Open Request (OPEN Function Code) on page 43

• GSAM File Sequential Read Request (GN Function Code) on page 44

• GSAM File Reposition & Read Request (GU Function Code) on page 45

• GSAM File Write Request (ISRT Function Code) on page 46

• GSAM 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.

COBOL01 PCBNAME. 02 DBD-NAME PIC X(8).

02 SEG-LEVEL PIC X(2). 02 STATUS-CODE PIC X(2).

02 PROC-OPTIONS PIC X(4). 02 RESERVE-DLI PIC S9(5) COMP. 02 SEG-NAME-FB PIC X(8).

02 LENGTH-KEY-FB PIC S9(5) COMP. 02 NUMB-SENS-SEGS PIC S9(5) COMP. 02 KEY-FB-AREA PIC X(8).

02 LENGTH-U-REC PIC S9(5) COMP.

COBOL Diagram 3.8: GSAM PCB layout

PL/IDECLARE 1 PCBNAME BASED (PCB-POINTER), 2 DBD-NAME CHAR(8),

2 SEG-LEVEL CHAR(2), 2 STATUS-CODE CHAR(2),

2 PROC-OPTIONS CHAR(4), 2 RESERVE-DLI FIXED BIN(31,0), 2 SEG-NAME-FB CHAR(8),

2 LENGTH-KEY-FB FIXED BIN(31,0), 2 NUMB-SENS-SEGS FIXED BIN(31,0) 2 KEY-FB-AREA CHAR(8),

2 LENGTH-U-REC FIXED BIN(31,0);

PL/I Diagram 3.9: GSAM PCB layout


Pascaltype CHAR2 = packed array[1..2] of CHAR;

CHAR4 = packed array[1..4] of CHAR; CHAR8 = packed array[1..8] of CHAR;

PCBTYPE = record DBD-NAME :CHAR8;

SEG-LEVEL :CHAR2; STATUS-CODE :CHAR2; PROC-OPTIONS :CHAR4;

RESERVE-DLI :INTEGER; SEG-NAME-FB :CHAR8; LENGTH-KEY-FB :INTEGER;

NUMB-SENS-SEGS :INTEGER; KEY-FB-AREA :CHAR8;

LENGTH-U-REC :INTEGER; end;

Pascal Diagram 3.10: GSAM PCB layout

Cstruct { char db_name[8];

char seg_level[2]; char stat_code[2];

char proc_opt[4]; int _dli; char seg_name_fb[8];

int len_kfb; int nu_senseg; char key_fb_area[8];

int len_u_rec; } pcbname;

C Language Diagram 3.11: GSAM PCB layout

Assem bler LanguageGSPCB DSECTGSPCBDBD DS CL8 DBD NAME

GSPCBLEV DS CL2 SEGMENT LEVELGSPCBSTC DS CL2 STATUS CODE

GSPCBPRO DS CL4 PROCESSING OPTIONSGSPCBRSV DS F RESERVED FOR DLIGSPCBSFD DS CL8 SEGMENT NAME FEEDBACK

GSPCBLKY DS F KEY LENGTHGSPCBNSS DS F NO. OF SENSITIVE SEGMENTSGSPCBKFD DS F KEY FEEDBACK LEVEL

GSPCBLUR DS F 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 allows 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 will allocate a PCB for the application.


SPICE DL/I Processing of File DD Name

Whenever possible, SPICE DL/I will use the DD name(s) defined in the GSAM DBD to

satisfy a DL/I request to a GSAM DBD. Otherwise, it will use the DBD name as DD

name. The following table defines SPICE DL/I processing of GSAM DD names:

Situation File Processed by SPICE DL/I

DBD not found 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” tothe request .No file allocated to DD

name specified in DBD

Otherwise T he file allocated to the DD name defined in the GSAM DBD.

T able 3.1: SPICE DL/I DD name select ion

SPICE DL/I GSAM File Record Processing


Programs that process records of variable or undefined length may determine the lengths

of records read, and specify the lengths of those written.

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.


GSAM File Open Request (OPEN Function Code)

SPICE GSAM files are opened in SPICE DL/I with 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 will open it upon the first DL/I statement that references it.



>>--- OPEN ---.--- gsam pcb ---.---.----------------.----------------->< +--- gsam aib ---+ +--- i/o area ---+

DL/I Diagram 3.13: Open GSAM file

DescriptionOPEN


“OPEN”.gsam pcb

The name of the area in your program that contains the GSAM PCB.gsam aib


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 following character

values.

• “INP” for an input data set.

• “OUT” for an output data set.

• “OUTA” for an output data set with ASA control characters.

• “OUTM” for an output data set with machine control characters.

Notes

If the request is the first reference to the GSAM PCB following a restart, SPICE DL/I

will automatically reposition the file to its position at the restart checkpoint.

Examples

01 FUNC-OPEN PIC X(04) VALUE 'OPEN'.01 INDIC-OUTPUT PIC X(04) 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 with GSAM PCB GSAM-PCB.


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.



>>--- GN ---.--- gsam pcb ---.--- i/o area ---.-----------.--------->< +--- gsam aib ---+ +--- rsa ---+

DL/I Diagram 3.14: Read record from GSAM file (GN funct ion code)

DescriptionGN


“GN ”.gsam pcb




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 which 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 all the records in the file have been read, a status code of “GB” is returned in the PCB.


Examples

01 FUNC-GN PIC X(04) VALUE 'GN '.01 REC-IN-AREA.


LINKAGE SECTION.

01 GSAM-PCB. 02 GSAM-DBD PIC X(08).

02 ... gsam pcb layout


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 funct ioncode)

The example reads the next record from the file associated with PCB GSAM-PCB, and

stores it in structure REC-IN-AREA. SPICE DL/I will 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.



>>--- GU ---.--- gsam pcb ---.--- i/o area --- rsa ----------------->< +--- gsam aib ---+

DL/I Diagram 3.15: Re-posit ion GSAM file and read record (GU funct ioncode)

DescriptionGU


“GU ”.gsam pcb





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

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 PIC X(04) VALUE 'GU '.01 REC-IN-AREA.

02 FIELD-1 PIC X(16) VALUE SPACES.01 RSA 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-posit ion input file and read record (GUfunction code)

The example reads the record from the file associated with PCB GSAM-PCB, whose

address is stored in field RSA. The record is stored into structure REC-IN-AREA.

GSAM File Write Request (ISRT Function Code)

To write the next sequential record to a SPICE GSAM file, issue a DL/I statement using

the ISRT function code.



>>--- ISRT ---.--- gsam pcb ---.--- i/o area ---.-----------.--------->< +--- gsam aib ---+ +--- rsa ---+

DL/I Diagram 3.16: Write record to GSAM file (ISRT funct ion code)

DescriptionISRT


“ISRT”.gsam pcb





The name of the area in your program from which SPICE DL/I should write 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


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 which SPICE DL/I should

place the record search argument (RSA) of the record written by SPICE DL/I.

This value may be used in a subsequent GU request, to retrieve the record out of

sequence.

Notes



Examples

01 FUNC-ISRT PIC X(04) VALUE 'ISRT'.01 REC-OUT-AREA.


LINKAGE SECTION.

01 GSAM-PCB. 02 GSAM-DBD PIC X(08).



ENTRY 'DLITCBL' USING IO-PCB, ..., GSAM-PCB....

CALL 'CBLTDLI' USING FUNC-ISRT, GSAM-PCB, REC-OUT-AREA.

COBOL Example 3.10: Write record from output file (ISRTfunction code)

The example writes the next record to the file associated with 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 with 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 will close it upon the termination of the program.



>>--- CLSE ---.--- gsam pcb ---.-------------------------------------->< +--- gsam aib ---+

DL/I Diagram 3.17: Close GSAM file

DescriptionCLSE


“CLSE”.gsam pcb




GSAM DBD. The routine name “AIBTDLI” must be used.


Examples

01 FUNC-CLSE PIC X(04) VALUE 'CLSE'....

LINKAGE SECTION. 01 GSAM-PCB. 02 GSAM-DBD PIC X(08).


... 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 with GSAM PCB GSAM-PCB.


SPICE Services


• 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


A SPICE DL/I services test statement is imbedded at a point in the program where the

programmer wishes to test a failure. The facility is controlled by DD statements in the

application JCL. These JCL statements, typically assigned to DUMMY, define what action

SPICE is to perform when the application issues a SPICE services test statement,

abnormally terminate for instance. When the controlling DD statement is removed, the

SQL statement will process successfully. It is thereby possible to design a suite of JCL

that tests thoroughly the restart logic of a program.


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.



>>--- TEST ---.--- i/o pcb ---.---.----------------.------------------>< +--- i/o aib ---+ +--- i/o area ---+

DL/I Diagram 3.18: SPICE services test facility

DescriptionTEST


“TEST”.i/o pcb

The name of the area in your program that contains the I/O PCB.i/o aib


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 will

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 will be controlled by the following

DD names://A1234DIE DD DUMMY

If this DD name is found in the program JCL, SPICE will immediately Abend with

code 4090.//A1234ERR DD DUMMY

If this DD name is found in the program JCL, SPICE will return a PCB status code of

“ZZ”.


Examples

01 FUNC-TEST PIC X(04) VALUE 'TEST'. 01 TEST-PREFIX PIC X(05) VALUE 'TESTS'.

... LINKAGE SECTION. 01 IO-PCB.


... 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 funct ion code)

The example will request the SPICE DL/I services testing facility. The action SPICE

will take depends upon the job JCL DD statements.


SPICE DL/I Statement

Parameter Summary

This section describes the following 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


>--------------.------------------------------------.----------------->< | |

| .----------------------------. | | | | |


>>--- CHKP ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+

>--------------.------------------------------------.----------------->< | |

| .----------------------------. | | | | |


>>--- CCHK ---.--- i/o pcb ---.--- i/o area len --- i/o area ---------> +--- i/o aib ---+

>--------------.------------------------------------.----------------->< | |

| .----------------------------. | | | | |


>>--- ROLB ---.--- i/o pcb ---.---.----------------.------------------>< +--- i/o aib ---+ +--- i/o area ---+


>>--- 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 DL/I™ Restart Database Administrat ion 5518 June 2009 © 1993,2009 Span Software Consultants Limited

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 HDAM SPICE Restart Databases.

! SPICD DEDB SPICE Restart Databases.

! SPICM MSDB SPICE Restart Databases.

Any values may be chosen for the remaining characters.


IMS System Preparation

The IMS HDAM SPICE Restart Database must be defined to the IMS system. The

following 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:

• HDAM Restart Database Creation on page 57

• DEDB Restart Database Creation on page 58

• MSDB Restart Database Creation on page 59


HDAM Restart Database Creation

The following steps should be performed, to create an HDAM SPICE Restart Database:

1) Create and compile the database DBD.

• The name of the database must begin with “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 will use the database.

2) Define the database to the IMS system that will use it.

3) Define the database to DBRC, and incorporate it into your database backup and

recovery system.

4) Allocate the database and define appropriate security.

5) Create or modify a PSB, to include a load PCB for the new database.

6) Create a dynamic allocation definition for the new database, if required.

7) 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.

8) Add a PCB for the database to all the required SPICE utility program and

subsystem PSBs.

9) 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.

10) Generate ACBs as necessary.

The following 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

Member Name Notes

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 allocat ing and init ializing an IMS

HDAM SPICE restart database. SPICE messages

SPI0412I and SPI0107W may be issued.

T able 5.1: IMS HDAM SPICE restart database installat ion


DEDB Restart Database Creation

The following steps should be performed, to create a DEDB SPICE Restart Database:

1) Create and compile the DBD for the database.

• The database name must begin with 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


• All segments in a DEDB are of variable length: an IMS restriction.

However, SPICE always inserts and replaces its segments at their

maximum length. This optimizes IMS Fast Path replace performance.


3) Define the database to DBRC, and incorporate it into your database backup and

recovery system.

4) Allocate the database and define appropriate security.

5) Initialize the database with the Fast Path DEDB initialization utility.


subsystem PSBs. Generate ACBs as necessary.

7) Create a dynamic allocation definition for the new database, if required.

8) Start the IMS system. If the system is already running, issue an IMS /START DB

command against the database.

9) 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.





JCL and source data that will create and initialize an IMS DEDB SPICE Restart

Database.

Library

Member Name Notes

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 allocat ing 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 act ive for this job.

T able 5.2: IMS DEDB SPICE restart database installat ion


MSDB Restart Database Creation

The following steps should be performed, to create an MSDB SPICE Restart Database:

1) Create and compile the DBD for the database.

• The database name must begin with 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



3) 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 with its sequence number.


subsystem PSBs. Generate ACBs as necessary.

5) Define appropriate security.

6) Restart the IMS system, loading up the new MSDB from the initialization file

generated in the earlier step.

7) Initialize the database, using a utility PSB containing the new database. Topic


8) Incorporate the database into your MSDB backup and recovery system.





JCL and source data that will create and initialize an IMS MSDB SPICE Restart

Database.

Library

Member Name Notes

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 allocat ing 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 act ive for this job.

T able 5.3: IMS MSDB SPICE restart database installat ion

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.


IMS Restart Database Considerations

When designing the database arrangements for SPICE DL/I, the following considerations

should be reviewed.

SPICE Restart Database usage

Typically, SPICE Restart Databases are not large, and SPICE applications do not place a

heavy load upon them. As with any other database however, 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 between

administrative convenience, which 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 follows:

BMP Applications

More than one executing BMP can share the same SPICE Restart Database. It is,

therefore, possible for SPICE Restart Databases to be shared between 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, however, 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. Two alternatives are suggested. The application could be

executed as BMPs, or IMS database block level sharing may be used for the SPICE

Restart Database.


SPICE Restart Database Security

As with 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 following table gives the level of access to the SPICE

Restart Database required by different categories of use.

access Use

full • SPICE Restart Database administrator

read and write • SPICE applicat ion programs• System Administ rat ion personnel tasked to administer SPICE

applicat ions, e.g. to issue SPICE Utility update commands such

as CHANGE

read only • System Administ rat ion personnel tasked to monitor SPICE

applicat ions, 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 will accumulate in the SPICE Restart Database for PSBs

and jobs that are no longer run. Such entries can be deleted from the tables with the

SPICE operator facilities.

WARNINGGreat care should be

taken with thisfacility!

By default, SPICE will not delete entries for PSBs and jobs that are active. It does,

however, 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 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.


taken with thisoption!

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.


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 following 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 following 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.


The following table gives details of the SPICE DL/I modules that may need to be link-

edited with 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 following

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 with the following LE

options:

• TRAP(OFF,NOSPIE)


Run Time Environments

Under SPICE DL/I, application programs can execute in the following 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 following environments:

• The TSO DB2 command processor, DSN, in foreground and background.

• Other compatible call attachment facility environments.

The following table illustrates the supported environments:

Installed SPICE Products

Execute inIMS

regions

Executeunder

DB2 DSNIssue SQLstatements

IssueDL/I

statements

SPICE DL/I yes no yes, but SPICEdoes not monitorthem for restartcritical events, e.g.backout.

yes

SPICE SQL no yes yes no

SPICE SQL & SPICE DL/I

yes yes yes in IMSregionsonly.

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 will 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 will 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 with name SPIOFDB2, which may be allocated to DUMMY.


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 written

to by SPICE, SPICE GSAM files must be initialized with 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 following example illustrates the

JCL required to allocate disk and tape SPICE GSAM files.

//DISK EXEC PGM=IEBGENER//SYSUT1 DD DSN=SPICE.SPI31.SAMPLIB(PPURTX4),DISP=SHR

//SYSUT2 DD DISP=(NEW,CATLG),DSN=SPICE.SPI31IVP.SE1DATA.SSAMFB,// UNIT=3390,VOL=SER=SPIVOL,// SPACE=(TRK,(1,1)),

// DCB=(LRECL=80,BLKSIZE=160,RECFM=FB)//SYSPRINT DD DUMMY

//SYSIN DD DUMMY//*//TAPE EXEC PGM=IEBGENER

//SYSUT1 DD DSN=SPICE.SPI31.SAMPLIB(PPURTX4),DISP=SHR//SYSUT2 DD DISP=(NEW,CATLG),DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB,// UNIT=TAPE,VOL=SER=SPISTV,FILE=(1,SL),

// DCB=(RECFM=FBA,LRECL=80,BLKSIZE=8000)//SYSPRINT DD DUMMY//SYSIN DD DUMMY

JCL Example 5.1: Allocate SPICE GSAM sequential files


Application Program JCL

IMS BMP Execution of SPICE Application

The following example illustrates the JCL required to run an application program

controlled by SPICE DL/I, as a BMP.

//PROCPURC EXEC IMSBATCH,MBR=my-pgm,PSB=my-psb,// IMSID=IVP1

//STEPLIB DD// DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR

// DD DSN=my.load.library,DISP=SHR//SYSPRINT DD SYSOUT=*

//IMS DD DISP=SHR,DSN=my-dbdlib

// DD DISP=SHR,DSN=my-psblib//SPIUDUMP DD SYSOUT=*//CEEDUMP DD SYSOUT=*

//SE1PRINT DD DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB,DISP=SHR//SE1DATA DD DSN=SPICE.SPI31IVP.SE1DATA.SSAMFB,DISP=SHR

JCL Example 5.2: Applicat ion program execution (BMP)

Consult IMS documentation for further information on IMS BMP JCL.

IMS BMP Execution of SPICE SQL Application


controlled by SPICE DL/I and SPICE SQL, as a BMP.

//PROCPURC EXEC IMSBATCH,MBR=my-pgm,PSB=my-psb,// IMSID=IVP1

//STEPLIB DD// DD DSN=DSN.SDSNLOAD,DISP=SHR// DD DSN=SPICE.SPI31SYS.SPILOAD,DISP=SHR

// DD DSN=my.load.library,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=*

//IMS DD DISP=SHR,DSN=my-dbdlib

// DD DISP=SHR,DSN=my-psblib

//SPIUDUMP DD SYSOUT=*//CEEDUMP DD SYSOUT=*

//SE1PRINT DD DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB,DISP=SHR//SE1DATA DD DSN=SPICE.SPI31IVP.SE1DATA.SSAMFB,DISP=SHR

JCL Example 5.3: SPICE SQL applicat ion program execution(BMP)

Consult IMS and DB2 documentation for further information on IMS BMP JCL and the

IMS attachment facility.


IMS Batch Execution of SPICE Application


controlled by SPICE DL/I, as an IMS batch program.

//PROCPURC EXEC DLIBATCH,

// MBR=my-pgm,PSB=my-psb


// DD DSN=my.load.library,DISP=SHR

//IEFRDER DD ... my IMS log

//SPIUDUMP DD SYSOUT=*//CEEDUMP DD SYSOUT=*//SE1PRINT DD DSN=SPICE.SPI31IVP.SE1PRINT.SSAMFB,DISP=SHR

//SE1DATA DD DSN=SPICE.SPI31IVP.SE1DATA.SSAMFB,DISP=SHR//SPICHSAM DD DSN=SPICE.SPI31IVP.SPICHSAM.DBASE,DISP=SHR

// ... my data bases

JCL Example 5.4: Applicat ion program execution (IMS batch)

Consult IMS documentation for further information on IMS batch JCL.

JCL Considerations

The requirements specific to SPICE are as follows:

IMS procedure The IMS procedure should include an allocation of the IMS

DBD library, assigned to DD name IMS.

//STEPLIB Ensure that the STEPLIB concatenation conforms with Run

Time Environments on page 65.

SPICE.SPI31SYS.SPILOAD The name of the load library dataset into which SPICE DL/I

was installed.

SPICE GSAM files Any physical sequential disk or tape file can be read or

written by SPICE, with full SPICE restart support.

SPICE GSAM 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 SPICE GSAM file types SPICE DL/I can also process the following 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.

//SPIUDUMP ... Should an abend occur during the execution of a SPICE DL/I

application program, SPICE will 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 will allocate a

SYSOUT=A dataset dynamically.

//SPIOFDB2 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 whose name

begins with the characters SPICR.


//<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™ Operat ion 7118 June 2009 © 1993,2009 Span Software Consultants Limited

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 following 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, without modification.

Most installations have as an objective the adoption of standard operating procedures

across application systems. Reducing the variety and complexity of application operation

can increase system reliability, and reduce operating costs. SPICE DL/I can contribute

significantly to this objective, as the same simple procedures can be utilized for all

application systems that use it.

With the exception of application program restart, SPICE DL/I applications are

administered either with the SPICE TSO/ISPF operator subsystem or the SPICE utility

program. Both provide easy to use facilities that allow the user to report upon and

administer applications.


SPICE TSO/ISPF Operator Subsystem

The SPICE operator subsystem is a set of interactive panels and programs that provide an

easy to use interface to SPICE. They allow operational personnel to administer SPICE

and its applications in an intuitive manner from a TSO terminal, through the use of the

subsystem's menus and extensive help and tutorial panels.

SPICE Utility Program

The SPICE utility program is a batch program. It can be used by operational personnel to

administer SPICE and its applications. Commands are read from the program's input

stream and processed accordingly. Printed reports may be obtained on the contents of a

SPICE Restart Database.


SPICE Operational Responsibilities

This section summarizes the uses to which the SPICE operator facilities can be put by

various categories of installation personnel.


• 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 following:

• To monitor the state of applications, by using the SPICE reporting options.

• To restart SPICE DL/I jobs, following system or program failure, by re-submitting

the JCL.

Operations Support Personnel

Staff responsible for resolving problems in the day to day operation of SPICE DL/I

applications can use the facilities of SPICE for the following:

• To determine the state of applications, by using the SPICE reporting options.

• To indicate that the application program is to be rerun, rather than restarted. This

decision may require consultation with development staff. Use of this facility can be

expected to be infrequent.

Operations Planning Personnel

Staff responsible for planning the implementation of applications that use SPICE DL/I

can use the facilities of SPICE for the following:

• To register new application programs in the SPICE Restart Database.

• To control which SPICE facilities are to be used.


Development Personnel

Staff responsible for developing SPICE DL/I applications can use the facilities of SPICE

for the following:

• To monitor the state of their application programs, by using the SPICE reporting

options.

• To control which SPICE facilities are to be used, according to the current testing

requirements of a program.

• Following application program failure, to restart their jobs or indicate that the

application program is to be rerun.

Database Administration and Technical Support Personnel

Staff responsible for the technical aspects of SPICE DL/I applications can use the

facilities of SPICE for the following:

• To create and initialize the SPICE Restart Database.

• To decide which SPICE DL/I facilities should be used, and select suitable parameter

values for them.

The implementation of these decisions might be performed by operations planning

personnel.


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, will enable

the user quickly to use the subsystem without reference to printed documentation.


• 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 when you start ISPF. It is possible, however, that the

SPICE operator subsystem was 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 following 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).


When the user selects the SPICE operator subsystem for the very first time, option 1

(SPICE) will not be displayed. It is necessary first to tell SPICE which IMS system you

wish SPICE to connect to. Select option 0 (OPTIONS) to do this. The following 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 Configurat ion Options Menu Panel

Select option 1 (SYSTEM TABLE). The following 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 wish to connect to, and press

Enter. The system you have selected will now have the indicator “current” displayed

alongside it. This system will be connected to when subsequently we select option 1

(SPICE) from the primary options menu.

Should the system you require not be displayed, you should consult with 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.


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 following

menu panel is displayed:

========================= SPICE Operator Subsystem ===========================

OPTION ===> _

------------------------------- Master Menu ----------------------------------

1 DB - Select Database entries

2 PROGRAM/PSB - Select Program(DB2) / PSB(IMS) Entries

3 JOB - 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) allows us to

enter SPICE utility commands through the SPICE operator subsystem.

Database Table Processing Options

If we select option 1 (DB) from the master menu, SPICE will display the following table

panel:



-------------------------- 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 Database T able Panel

The database table panel allows 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.


PSB Table Processing Options

If we select option 2 (PROGRAM/PSB) from the master menu SPICE will display the

following PSB table panel. There will be rows in the table for all PSBs registered in each

of the databases.



-------------------------- 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, rows will exist for all PSBs registered in the selected database.

The PSB table panel allows 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 we select option 3 (JOB) from the master menu SPICE will display the following job

table panel. There will be rows in the table for all the job entries of every registered PSB

in each database.



----------------------------- 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, rows will exist for all jobs of the selected PSB.

The job table panel allows 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 wander

around the options from the panels we have met. It is recommended that the help system

be used to explain the purpose of all the various options and subsidiary panels.


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 when

building commands for it, and the HELP command.


• 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 following 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


//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.


IMS BMP Execution of SPICE Utility, attached to DB2


utility program as an IMS BMP attached to a DB2 system. If SPICE SQL is installed, the

program will be able to process both IMS and DB2 SPICE Restart Databases.


//* 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


utility program as an IMS batch program.


//* DOC: EXAMPLE OF JCL TO RUN THE SPICE UTILITY IN BATCH.//*//BATCH EXEC DLIBATCH,MBR=SPIUTI00,PSB=SPIDBPSB


//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.


JCL Considerations

psb name The PSB used should contain PCB's for the SPICE databases that the

user wishes to process.

SPICE.SPI31SYS.SPILOAD The name of the load library dataset into which SPICE

DL/I was installed.

//SYSPRINT ... The SPICE utility command responses and reports are written to this

DD name. The reports are described in section SPICE Restart

Database Reports on page 83.

//SYSIN ... The SPICE utility commands are read from this DD name. The next

topic describes the rules for constructing these commands.

//SPIOFDB2 ... 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 whose name begins with the characters SPICR. Note

that SPICE will not issue any calls to this database. Only use these

options if SPICE SQL is installed.

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 following 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, wherever 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 will ignore any leading blanks

from the following line. A minus sign will not.

• Blank lines between 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 twice.


The following 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 /* COMMANDS MAY BE SPLIT */ - DBDNAME(SPICHSAM) /* ACROSS LINES AND EVEN */ - /* WORDS MAY BE SPLIT */ PSBNAME(ABC+

123) + JOBNAME('@ODDNAME')

Utility Example 5.4: Command conventions

SPICE Utility Program Help Command

SPICE includes a HELP command. The following 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, without 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 */ - HELP /* DESCRIPTION TERMINOLOGY */

Utility Example 5.5: HELP command


SPICE Restart Database Reports

This section describes the reports on the contents of the SPICE Restart Database that can

be obtained from the SPICE operator facilities. They are obtained with the LIST option

(SPICE operator subsystem) or LIST command (SPICE utility).

The SPICE Restart Database contains the following entry types:

PSB Entries Define the SPICE options that are to be used when the

named PSB is executed with 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.


• 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


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 DUMP option.

SPICE Utility Command

The following 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 --+

Utility Diagram 5.2: LIST command for PSB entries

PSBNAME(ALL) Select all PSB entries in the database. A one line report on each

entry will be generated.

FORMAT Generate a formatted report from the selected entries. This is the

default when a specific entry is selected.

DUMP Generate a hexadecimal dump of the contents of the selected entries.

Exam ples

/*-------------------------------------*/ /* LIST DBD... PSB ... EXAMPLES */

/*-------------------------------------*/

LIST DBDNAME(SPICHSAM) /* FORMATTED REPORT OF A */ -

PSBNAME(SPIVP4CP) /* SPECIFIC PSB ENTRY */

LIST /* LIST OF ALL PSB'S */ - DBDNAME(SPICHSAM) /* DEFINED IN THE RESTART */ - PSBNAME(ALL) /* DATABASE (ONE PER LINE) */

LIST DBDNAME(SPICHSAM) /* FORMATTED REPORT OF ALL */ - PSBNAME(ALL) /* PSB'S DEFINED IN THE */ -

FORMAT /* RESTART DATABASE */

LIST DBDNAME(SPICHSAM) /* FORMATTED REPORT AND */ -

PSBNAME(SPIUTI00) /* HEXADECIMAL DUMP OF A */ - FORMAT DUMP /* SPECIFIC PSB ENTRY */

Utility Example 5.6: LIST commands for PSB entries


Formatted Report Contents

The following example is an instance of a formatted report of a PSB entry.

PSB SPIVP4CP

entry created 2004.286 last change 0000.000 0:00:00.0 restart entry length 2030

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

PSB The name of the application program.

entry created, last change The date and time when the entry was created and last

altered by SPICE operator facilities.

restart entry length Length of job entry segment.

Commit Point Suppression Values of SPICE checkpoint suppression parameters. The

values labelled DB2 & IMS BMP regions apply when the

PSB is run as a BMP. The values labelled IMS BATCH

regions apply when the PSB is run as batch IMS. This

section of the report is further explained in topic Checkpoint

Suppression on page 107.

Application Timeout Values of SPICE application timeout parameters. The values

labelled DB2 & IMS BMP regions apply when the PSB is run

as a BMP. The values labelled IMS BATCH regions apply

when the PSB is run as batch IMS. 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. The values

labelled DB2 & IMS BMP regions apply when the PSB is run

as a BMP. The values labelled IMS BATCH regions apply

when the PSB is run as batch IMS. This section of the report is

further explained in topic Checkpoint Braking on page 116.In-Flight Restart

loop detection limit The maximum number of SPICE In-Flight Restarts that may be

issued without an intervening successful checkpoint. This

section of the report is further explained in topic SPICE In-

Flight Restart ™ on page 113.

Terminate Out of Sync The action that SPICE will take upon program termination when

the restart resources are out of synchronization, following a

‘ROLB’ for instance. This option is further explained in

Application Program Termination on page 119.


Other Indicators (when present)

SUSPENDED 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.

RESTART DISABLED Indicates that SPICE restart will 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.

(DEFAULT VALUES) 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 will take its parameters from the

PSB entry. Further information can be found in topic Default

Value Processing on page 106.

Dump Report Contents

The following 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 follows: Entry Header: +0000 00640064 E2D7E2C2 00000000 27100000 *....SPSB........*

+0010 00000000 00000000 51200000 E2D7C9E5 *............SPIV* +0020 D7F4C3D7 2004286F 00000000 0000000C *P4CP...?........*

+0030 0000000C 000007EE 00000000 00000000 *................* +0040 00000000 00000000 00000000 00000000 *................* +0050 E2D7C9E5 D7F4C3D7 40404040 40404040 *SPIVP4CP *

+0060 00050000 *....*

Report Example 5.8: DUMP Report of PSB Entry


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, following program failure.


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 DUMP option.



contents of job entries in the SPICE Restart Database.


>------------- PSBNAME --- ( -.- name -.- ) ------------------------------> +- ALL -+

>------------- JOBNAME --- ( -.- name -.- ) ------------------------------>

+- ALL -+

>--------------.------------.--.------------.--.----------.---------------><

+-- ACTIVE --+ +-- FORMAT --+ +-- DUMP --+

Utility Diagram 5.3: LIST command for job entries

PSBNAME(ALL) Select all PSB entries in the database. A one line report on each

entry will be generated.

JOBNAME(ALL) Select all job entries in the database for each selected PSB entry.

A one line report on each entry will be generated.

ACTIVE Select all job entries that are either executing or are awaiting

restart.

FORMAT Generate a formatted report on each of the selected entries. This

is the default when a specific job entry is selected.

DUMP Generate a hexadecimal dump of the contents of each of the

selected entries.


Exam ples

/*---------------------------------------*/ /* LIST DBDNAME... JOBNAME ... EXAMPLES */

/*---------------------------------------*/

LIST DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* FORMATTED REPORT OF A */ -

JOBNAME(ABC123) /* SPECIFIC JOB ENTRY */

LIST /* LIST OF ALL JOBS */ - DBDNAME(SPICHSAM) /* DEFINED IN THE RESTART */ + PSBNAME(SPIVP4CP) /* DATABASE FOR A SPECIFIC */ -

JOBNAME(ALL) /* PSB (ONE PER LINE) */

LIST /* LIST OF ALL JOBS AND */ -

DBDNAME(SPICHSAM) /* PSB'S DEFINED IN THE */ - PSBNAME(ALL) /* RESTART DATABASE (ONE */ - JOBNAME(ALL) /* PER LINE) */

LIST DBDNAME(SPICHSAM) PSBNAME(ALL) /* LIST OF ALL ACTIVE JOBS */ - JOBNAME(ALL) /* DEFINED IN THE RESTART */ -

ACTIVE /* DATABASE (ONE PER LINE) */

LIST /* FORMATTED REPORT OF ALL */ - DBDNAME(SPICHSAM) /* JOBS DEFINED IN THE */ + PSBNAME(SPIVP4CP) /* RESTART DATABASE FOR A */ -

JOBNAME(ALL) FORMAT /* SPECIFIC PSB */

LIST /* FORMATTED REPORT AND */ -

DBDNAME(SPICHSAM) /* HEXADECIMAL DUMP OF ALL */ + PSBNAME(SPIVP4CP) /* JOBS DEFINED IN THE */ + JOBNAME(ALL) /* RESTART DATABASE FOR A */ -

FORMAT DUMP /* SPECIFIC PSB */

Utility Example 5.9: LIST commands for job entries



The following 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

since last Statistics: since job start start/restart commit points issued by program 9 9

commit points issued to DBMS 9 9 number database entries updated 25 seconds elapsed 4

Report Example 5.10: Formatted Report of Job Entry

JOB, step, program 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 when the entry was created and last

altered by SPICE operator facilities.last start, last restart,

last finish The date and time when this execution of the program started,

was last restarted and completed.

Note: last restart can be zero, indicating that the job has not

been restarted since this execution started.

Note: last finish can precede last start This indicates that this

execution of the program has not yet reached completion; it is

either running or has abnormally terminated.

last commit The time and date when 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 will never be higher those of the preceding line in

the report.

Note: The two columns only differ after a failure of the program

has resulted in a restart, in which case the values in the first

column will be higher.

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 which the program has been executing, in seconds,

since the latest of last start and last restart.


Other Indicators (when present)

ACTIVE This text, when present, indicates that the specified job is

executing, or has failed and restart is required. SPICE will

perform restart processing when the job is next executed.

Absence of this text indicates that SPICE will perform normal

start processing when the job is next executed.

SUSPENDED 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.



The following 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


JOB The name of the job, suffixed by blanks or, when restart data

for this execution of the program is spread over multiple job

entries, a sequence number.

restart item <SSPD> 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 <SPAD> 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.

Default Values Entry ReportThe values in the default values entry are used by SPICE when executing application

programs with PSBs whose SPICE Restart Database entries indicate that the default

values are to be used.


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

DUMP option.



default SPICE values entry in the SPICE Restart Database.


>------------- DEFAULTS -------------------------------------------------->

>--------------.----------.----------------------------------------------->< +-- DUMP --+

Utility Diagram 5.4: LIST command for default value entries

DUMP Generate a hexadecimal dump of the contents of the entry.

Exam ples

/*----------------------------------------*/ /* LIST DBDNAME... DEFAULTS EXAMPLES */

/*----------------------------------------*/

LIST DBDNAME(SPICHSAM) /* FORMATTED REPORT OF */ -

DEFAULTS /* DEFAULT VALUES ENTRY */

LIST DBDNAME(SPICHSAM) /* FORMATTED REPORT AND */ + DEFAULTS /* HEXADECIMAL DUMP OF */ - DUMP /* DEFAULT VALUES ENTRY */

Utility Example 5.12: LIST command for default values entry



The following example is an instance of a formatted report of the default values entry.

DEFAULT ENTRY


Commit Point Suppression thresholds: seconds updates

DB2 & IMS BMP regions 30 1000 IMS BATCH regions 0 0 Application Timeout


IMS BATCH regions 0 0 Commit Point Braking wait period: seconds

DB2 & IMS BMP regions 0 IMS BATCH regions 0 In-Flight Restart Terminate Out of Sync -Keep Restart


Report Example 5.13: Formatted Report of Default Values entry

DEFAULT ENTRY Indicates that this is the default values entry.

entry created The date and time when the database was initialized.

last change The date and time when the entry was last altered by SPICE

utility command.

restart entry length Length of job entry segment.

Commit Point Suppression Values of SPICE checkpoint suppression parameters used

with PSB's whose database entries specify use of the default

values. The values labelled DB2 & IMS BMP regions

apply when the PSB is run as a BMP. The values labelled

IMS BATCH regions apply when the PSB is run as batch

IMS. This section of the report is further explained in topic

Checkpoint Suppression on page 107.

Application Timeout Values of SPICE application timeout parameters used with PSBs

whose database entries specify use of the default values. The

values labelled DB2 & IMS BMP regions apply when the PSB

is run as a BMP. The values labelled IMS BATCH regions

apply when the PSB is run as batch IMS. 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 with PSBs

whose database entries specify use of the default values. The

values labelled DB2 & IMS BMP regions apply when the PSB

is run as a BMP. The values labelled IMS BATCH regions

apply when the PSB is run as batch IMS. This section of the

report is further explained in topic Checkpoint Braking on page

116.In-Flight Restart

loop detection limit The maximum number of SPICE In-Flight Restarts that may be

issued without an intervening successful checkpoint. This




Terminate Out of Sync The action that SPICE will take upon program termination when

the restart resources are out of synchronization, following a

‘ROLB’ for instance. This option is further explained in

Application Program Termination on page 119.


The following 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 follows: Entry Header: +0000 00640064 E2D7E2C2 00000000 27100000 *....SPSB........*

+0010 00000000 00000000 41200000 40404040 *............ * +0020 40404040 2004284F 00000000 2004284F * ...|.......|*

+0030 1745316F 000007EE 000003E8 00000BB8 *...?.......Y....* +0040 00000000 00000000 00000000 00000000 *................* +0050 40404040 40404040 40404040 40404040 * *

+0060 00050000 *....*

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.


To obtain the MSDB contents report, select option MSDB against the database, from the

database table panel.

SPICE Utility CommandThe following 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

MSDBINDEX 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.

FORMAT Generate a formatted report on each of the selected entries. This

is the default when a specific entry is selected.

DUMP Generate a hexadecimal dump of the contents of each of the

selected entries.


Exam ple

/*---------------------------------------*/ /* LIST DBDNAME...MSDBINDEX... EXAMPLES */

/*---------------------------------------*/

LIST DBDNAME(SPICMSAM) MSDBINDEX(ALL) /* MSDB CONTENTS REPORT */

Utility Example 5.15: LIST command for MSDB entries

Report Contents

The following example is an instance of an MSDB contents report.

SPSB ALLOCATED MSDB 0001 across down SPSB SPIDCPSB ALLOCATED MSDB 0002 across down

SPSB SPIVP4CP ALLOCATED MSDB 0003 across down 0007SCHK JOBX 0001 FREE MSDB 0004 across down SCHK JOBX 0002 FREE MSDB 0005 across down

SCHK JOBX 0003 FREE MSDB 0006 across down SCHK JOBA 0001 ALLOCATED MSDB 0007 across 0008 down

SCHK JOBA 0002 ALLOCATED MSDB 0008 across 0012 down SPSB SPIVP5CP ALLOCATED MSDB 0009 across down 0010SCHK JOBP 0001 ALLOCATED MSDB 0010 across 0011 down

SCHK JOBP 0002 ALLOCATED MSDB 0011 across down SCHK JOBB 0001 ALLOCATED MSDB 0012 across down SCHK JOBA 0001 FREE MSDB 0013 across down

SCHK JOBA 0002 FREE MSDB 0014 across down SCHK JOBC 0001 FREE MSDB 0015 across down MSDB FREE MSDB 0016 across down

MSDB FREE MSDB 0017 across down MSDB FREE MSDB 0018 across down MSDB FREE MSDB 0019 across down

MSDB FREE MSDB 0020 across down MSDB FREE MSDB 0021 across down

MSDB FREE MSDB 0022 across down MSDB FREE MSDB 0023 across down MSDB FREE MSDB 0024 across down

MSDB FREE MSDB 0025 across down

Report Example 5.16: Formatted Report of Default Values entry

SPSB/SCHK/MSDB Indicates that when the entry was last allocated, it was 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.

ALLOCATED Indicates that the entry is currently allocated to a restart database

entry.

FREE Indicates that the entry is available for use as a restart database

entry.

MSDB nnnn The index of the entry in the database.

across nnnn The index of the next (SCHK) entry at the same hierarchical level.

down nnnn 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 water mark', may be calculated by adding up the number of entries not labelled as

SPSB or SCHK.


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 followed when

certain error situations are encountered.


• 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 will be registered automatically. Alternatively the SPICE operator

facilities may be used explicitly to register a PSB in the SPICE Restart Database.


PSBs can be registered in a SPICE Restart Database by selecting option INSERT from the

PSB table panel.


The following 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 --- ) ------------------------------><

Utility Diagram 5.6: INIT command to register 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


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, following 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

since last Statistics: since job start start/restart commit points issued by program 9 9

commit points issued to DBMS 9 9 number database entries updated 25 seconds elapsed 4

Report Example 5.18: Report of running SPICE jobs

ACTIVE Absence of this text indicates that SPICE is awaiting 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 will perform restart processing the

next time the job executes the program.

last start, last stop If the last execution of the program for this job ran

successfully to completion, stop time will succeed start

time.

Application Program Restart

The following 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 with a SPICE GSAM file that requires that the file be re-

created or re-allocated, the procedures detailed in item SPICE GSAM File

Recovery/Restart must be followed.


2) Resubmit the failed application job step. No modification is required to the step JCL.

SPICE will 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.


Display the SPICE operator subsystem job table panel. Jobs that are executing or

awaiting 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 SPICEJOB ACTIVEJOB SPICEJOC

Utility Example 5.19: Report of act ive SPICE jobs

ACTIVE This text, when present, indicates that the specified job is either

executing or has failed and restart is required. SPICE will

perform restart processing the next time the job executes the

program. Absence of this text indicates that SPICE will not

restart the program when the job is next executed.


Application Program Rerun

After an application or system failure, restartable SPICE DL/I programs will normally be

restarted from their last checkpoint (otherwise they would not have been so designed!).

However, it is sometimes necessary, typically after a severe application logic failure, to

rerun the job. For example, an application may have written corrupt entries into

application databases, and committed them with 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 when

the job started its execution.

The following 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 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.


The following 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 applicat ion jobstep rerun

RERUN Allow the selected program to be rerun with the selected

jobname.

RESTART Reverse the effect of an earlier CHANGE ... RERUN command.

Note: This command will fail if it is issued against a

program/job that has completed successfully.


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) /* ONLY ISSUE THIS COMMAND */ - /* PSBNAME(SPIVP4CP) /* TO 'UNDO' THE EFFECT OF */ -

/* JOBNAME(ABC123) /* AN EARLIER 'RERUN' */ - /* RESTART /* 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,

forward recovery of SPICE GSAM output files is not available following irrecoverable

I/O errors.

End of Extent/Volume Failure (e.g. B37 Abends)

Problems can occur with 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, with the utility REPRO command.

WARNINGIt 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 applicationcorruption.



The utility REPRO command is used to copy a SPICE GSAM file to another dataset,

without 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 f ile, may then be used in a successful restart of the program.

This procedure is necessary because, at each checkpoint, SPICE writes 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

written 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

would be consolidated into full size blocks.

The following 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

PSBNAME The name of the PSB that the failed job was executing.

JOBNAME The name of the job that failed.

INFILE The DD name of the file to be recovered. This must be the same

DD name as was used in the failed job.

OUTFILE The DD name of the file to be written to.

The command creates a copy of a SPICE GSAM file in use by a job awaiting restart.

Any records written following the restart checkpoint are truncated from the input file, and

not written to the output file. After the copy has completed, the SPICE Restart Database

will reflect the restart position in the copy. The new file should then be used for the

restart.


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 following:

• 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 written to it and the address of the restart

position, which replaces the value in the restart entry.

After the copy has completed, the SPICE Restart Database will reflect the required restart

position in the copy. The new file should then be used for the restart.

Note the following considerations:

• The job must be awaiting 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 with 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 with the specified INFILE DD name was open at the time of the

restart checkpoint, the command will fail with message SPI0456. This message is also

issued when the command fails because the user misspells the DD name. It is

possible to check which files were 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 following procedure is suggested for use following SPICE GSAM output file failure,

an X37 Abend for instance:

1) Rename the failed file. This will protect against the possibility of attempting to

restart the job with 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.


Exam ple


//* 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) -


INFILE(SE1PRINT) OUTFILE(SE1PRI99) LIST DBD(SPICHSAM) -


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 The IMS procedure should include an allocation of the IMS

DBD library, assigned to DD name IMS.

UNIT The device type of the output file need not be the same as

that of the input file.

RECFM The record format of the output file must be the same as that

of the input file.

LRECL The record length of the output file must be the same as that

of the input file.

BLKSIZE The blocksize need not be the same.


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 with the minimum of disruption to on-

line users.

SPICE applications can be suspended by use of the SPICE operator facilities. Each job

will then ABEND, user code 4090, after its next checkpoint. Message SPI0101I will 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.


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.


The following 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 applicat ion execution

SUSPEND Cause the selected PSBs and jobs to abend following their next

checkpoint.

RELEASE Allow the selected PSBs and jobs to restart.

Exam ples


/*------------------------------------*/ /* 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) /* THIS WILL CRASH ALL */ - JOBNAME(ALL) /* EXECUTING SPICE DL/I */ -

SUSPEND /* APPLICATION PROGRAMS ! */

CHANGE DBDNAME(SPICHSAM) PSBNAME(ALL) /* ALLOW ALL PSB'S TO */ - JOBNAME(ALL) /* BE RESTARTED */ - RELEASE

Utility Example 5.23: CHANGE ... SUSPEND command

PSB Entry Report SpecificationThe suspend status of PSB and job entries is shown 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 follows:

PSB entry report:

SUSPENDED 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.job entry report:

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.


Controlling SPICE Features

This section describes how certain of the principal facilities of SPICE should be

configured and used.


• 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.


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.


The following diagram defines the variant of the CHANGE command that does this:

>>--- CHANGE --- DBDNAME --- ( --- name --- ) ---------------------------->

>--------------- PSBNAME --- ( --- name --- ) ---------------------------->

>------------------- USEDEFAULTS --- ( -.- YES -.- ) ---------------------><

+- NO --+

Utility Diagram 5.10: CHANGE command to select non-default values for a PSB


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) /* USE VALUES SPECIFIC TO */ - PSBNAME(SPIVP5CP) /* THE PSB */ -

USEDEFAULT(YES)

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 shown 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 Checkpoint

Suppression, Application Timeout and Checkpoint

Braking sections of the report. Absence of this text

indicates that the parameters are taken from the specific

PSB entry.

Checkpoint Suppression


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


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.



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).


The following 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

PSBNAME/DEFAULTS 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 PSBs.

TIME Specifies the maximum elapsed interval, in seconds, that SPICE

should monitor before passing a subsequent checkpoint request

to IMS. The first value is used when the PSB is used by a BMP,

the second when it is used by an IMS batch program. Values of

0 disable SPICE checkpoint suppression.

UPDATES Specifies the maximum number of database table rows that

SPICE should monitor before passing a subsequent checkpoint

request to IMS. The first value is used when the PSB is used by

a BMP, the second when it is used by an IMS batch program.

Values of 0 disable SPICE checkpoint suppression.


Exam ples

/*------------------------------------*/ /* EXAMPLES OF CHANGE COMMANDS FOR */

/* COMMIT POINT SUPPRESSION */ /*------------------------------------*/

CHANGE DBDNAME(SPICHSAM) DEFAULTS /* INTRODUCE COMMIT POINT */ - COMMIT(TIME(30) /* SUPPRESSION FOR ALL */ -

UPDATES(1000) ) /* 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 /* DISABLE COMMIT POINT */ - COMMIT(TIME(0) /* SUPPRESSION FOR */ -

UPDATES(0)) /* 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


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








Utility Example 5.1: Report of SPICE checkpoint suppression parameters

Commit Point Suppression

(DEFAULT VALUES) This text, when present, indicates that the checkpoint

suppression parameters were 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.


thresholds:

DB2 & IMS BMP regions This row contains the checkpoint suppression parameters

used by SPICE for this PSB, when it is run as an IMS BMP.

IMS BATCH regions This row contains the checkpoint suppression parameters

used by SPICE for this PSB, when 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

wait states whilst 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 when a program exceeds an elapsed time threshold for

uncommitted database updates. Application timeout by update count occurs when a

program exceeds an elapsed database row update threshold without issuing a checkpoint

request. SPICE will then take one of the following actions:

• Issue a message to the z/OS operator.

• Issue a message to the z/OS operator asking whether the program should be

terminated abnormally or be allowed 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.


To alter the parameters that control application timeout, first select the checkpoint


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.




To alter the checkpoint suppression parameters, change the displayed values and select

option 2 (TIMEOUT).




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 applicat ion t imeout




selects parameters for executing programs.

WTO Specifies that upon application timeout SPICE should issue

message SPI0211W to the z/OS operator.

WTOR Specifies that upon application timeout SPICE should issue

message SPI0212W and request SPI0212A to the z/OS operator

asking whether the program should be terminated abnormally or

be allowed to continue.

ABEND Specifies that upon application timeout SPICE should issue

message SPI0213W to the z/OS operator and terminate the

program abnormally.

TIME Specifies the interval, in seconds, that should elapse before

SPICE instigates application timeout processing. The timing

begins from the first database table update following a IMS

checkpoint. The first value is used when the PSB is used by a

BMP, the second when 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 which IMS and/or

z/OS are likely to suspend application program processing.

UPDATES Specifies the number of database rows that should occur before

SPICE instigates application timeout processing. The count

begins from the first database table update following a IMS

checkpoint. The first value is used when the PSB is used by a

BMP, the second when it is used by an IMS batch program.

Values of 0 disable SPICE application timeout by updates.


Exam ples


/* APPLICATION TIMEOUT */ /*------------------------------------*/

CHANGE DBDNAME(SPICHSAM) DEFAULTS /* INTRODUCE APPLICATION */ - TIMEOUT(WTO /* TIMEOUT FOR ALL DEFAULT */ -

TIME(300,0) /* VALUE PSB'S, OPERATOR */ - UPDATES(10000,0)) /* NOTIFIED, NO ABEND */

CHANGE DBDNAME(SPICHSAM) DEFAULTS /* CHANGE TO ABEND ACTION */ - TIMEOUT(ABEND) /* UPON APPLICATION TIMEOUT*/

CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* INTRODUCE APPLICATION */ - TIMEOUT(WTOR /* TIMEOUT FOR SPECIFIC */ - TIME(600) /* PSB, OPERATOR TO */ -

UPDATES(5000)) /* 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) /* CHANGE TO APPLICATION */ - TIMEOUT(ABEND) /* TIMEOUT ACTION OF ABEND */

CHANGE DBDNAME(SPICHSAM) DEFAULTS /* FOR ALL PSBS */ - TIMEOUT(ABEND) /* */

Utility Example 5.2: CHANGE command for controlling applicat ion t imeout


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.


PSB SPIVP4CP








Utility Example 5.3: Report of SPICE applicat ion t imeout parameters

Application Timeout

(DEFAULT VALUES) This text, when present, indicates that the application

timeout parameters were 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 what action SPICE will 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

SPICE for this PSB when it is run as an IMS BMP.

IMS BATCH regions This row contains the application timeout thresholds used by

SPICE for this PSB when 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 allows application programs to continue

processing successfully despite encountering certain failure conditions. For instance,

contention between batch programs can result in the database management system

backing out uncommitted updates, informing the program with an error code. Normally,

the application would 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 without disruption. To cater for when the error condition

persists, SPICE limits the number of In-Flight Restarts that a program can issue without

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.



To alter the parameters that control application timeout, first select the checkpoint


PSB Entry


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.



(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).



the application timeout parameters:


>-------------.- DEFAULTS ---------------------.----------------------------> +- PSBNAME --- ( --- name --- ) -+

>--------------- RESTARTLIMIT -- ( --- value --- ) -------------------------><

Utility Diagram 5.13: CHANGE command to control applicat ion t imeout

PSBNAME/DEFAULTS 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.

RESTARTLIMIT Specifies the maximum number of SPICE In-Flight Restarts

that the program can issue without 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 applicat iont imeout



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








Utility Example 5.5: Report of SPICE applicat ion t imeout parameters

In-Flight Restart

(DEFAULT VALUES) This text, when present, indicates that the application

timeout parameters were 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.

loop detection limit The maximum number of SPICE In-Flight Restarts that may

be issued without an intervening successful checkpoint. This




SPICE Services Test Facility

The SPICE services test facility allows 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 when the application issues a SPICE

services statement.

The following JCL example illustrates the DD names used to control this facility:


//* DOC: THIS JOB EXECUTES THE SAMPLE APPLICATION.//*//PROCPURC EXEC IMSBATCH,MBR=SPIVCPUR,PSB=SPIVP4CP,

// IMSID=IVP1...

//TESTSDIE DD DUMMY /* MAKE THE PROGRAM ABEND */...//


//* 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

//TESTSDIE Presence of this DD name causes SPICE to terminate the

program abnormally, when a SPICE services test facility

statement specifying prefix “TESTS” is issued by the program.

//TESTSERR Presence of this DD name causes SPICE to return a non-zero

SQLCODE, when 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 wait 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.



To alter the parameters that control checkpoint braking, first select the checkpoint control

options panel:

PSB Entry


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.


Select option Edit against the database from the database table panel. Select option 1


To alter the checkpoint braking parameters, change the displayed values and select option

3 (BRAKING).



the checkpoint braking parameters:


>------------.-- DEFAULTS ----------------------.---------------------------> +-- PSBNAME --- ( --- name --- ) --+

>--------------- BRAKING -- ( --- TIME -- ( - value - , - value - ) --- ) --><

Utility Diagram 5.14: CHANGE command to control checkpoint braking





TIME Specifies the interval, in seconds, for which SPICE will suspend

the application, following a IMS checkpoint. The first value is

used when the PSB is used by a BMP, the second when it is used

by an IMS batch program. Values of 0 disable SPICE

checkpoint braking.


Exam ples


/* COMMIT POINT BRAKING */ /*------------------------------------*/

CHANGE DBDNAME(SPICHSAM) /* INTRODUCE 15 SECONDS */ - DEFAULTS /* BRAKING FOR ALL BMP'S */ -

BRAKING( /* WHOSE PSB'S USE DEFAULT */ - TIME(15,0)) /* VALUES */

CHANGE DBDNAME(SPICHSAM) /* INTRODUCE 30 SECONDS */ - PSBNAME(SPIVP4CP) /* BRAKING FOR BMP'S USING */ - BRAKING(TIME(30,0)) /* SPECIFIC PSB */

CHANGE DBDNAME(SPICHSAM) /* DISABLE BRAKING FOR ALL */ - DEFAULTS /* PSB'S THAT USE */ -

BRAKING(TIME(0,0)) /* DEFAULT VALUES */

CHANGE DBDNAME(SPICHSAM) /* DISABLE BRAKING FOR ALL */ -

PSBNAME(ALL) /* PSB'S THAT DO NOT USE */ - BRAKING(TIME(0,0)) /* DEFAULT VALUES */

Utility Example 5.7: CHANGE command for controlling checkpointbraking


The SPICE checkpoint braking parameters can be found in the section headed

Checkpoint Braking 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 last change 91.095 17:40:34.7 restart entry length 2030







Utility Example 5.8: Report of SPICE checkpoint braking parameters

Checkpoint Braking


braking parameters were taken from the default



specific to this PSB entry.wait period:

DB2 & IMS BMP regions This row contains the checkpoint braking interval, in

seconds, used by SPICE for this PSB, when it is run

as an IMS BMP.


IMS BATCH regions This row contains the checkpoint braking interval, in

seconds, used by SPICE for this PSB, when 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 when the SPICE Restart Database is out of

synchronization with 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.


To alter the parameters that control out of synchronization termination, first select the

restart control options panel:

PSB Entry


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.


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).



the out of synchronization option parameter:



>------------.-- DEFAULTS ----------------------.---------------------------> +-- PSBNAME --- ( --- name --- ) --+

>--------------- OUTOFSYNCTERM -- ( -.- KEEPRESTART -.- ) ------------------><

+- ABEND -------+

Utility Diagram 5.15: CHANGE command to control out ofsynchronizat ion terminat ion





OUTOFSYNCTERM Specifies the action SPICE should take following out of

synchronization termination.

KEEPRESTART Retain the restart and terminate normally.

ABEND Retain the restart and terminate abnormally.

Exam ples


/* 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 ofsynchronizat ion terminat ion



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


this report may be obtained.

PSB SPIVP4CP

entry created 91.079 15:54:15.0 last change 91.095 17:40:34.7 restart entry length 2030





DB2 & IMS BMP regions 0 IMS BATCH regions 0 In-Flight Restart Terminate Out of Sync -Keep Restart

Loop detection limit restarts 5

Utility Example 5.10: Report of SPICE out of sync terminat ion controlparameter

Checkpoint Braking


braking parameters were taken from the default



specific to this PSB entry.Terminate Out of Sync:

Keep Restart Retain restart data and terminate normally.

Abend Retain restart data and terminate abnormally.


Other Facilities

This section describes how to make use of those facilities not covered in other sections of

this chapter.


• 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.


To initialize the database select option INITIALIZE against the database from the database

table panel.


A variant of the INIT command of the SPICE utility program is used for this. The

following diagram defines the command:

>>--- INIT --- DBDNAME --- ( --- name --- ) -------------------------------->

>------------- DEFAULTS ---------------------------------------------------->

>----------------- SEGLEN --- ( -- value -- ) ------------------------------><

Utility Diagram 5.16: INIT command to init ialize restart database

SEGLEN 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.


Exam ple

/*------------------------------------*/ /* EXAMPLE OF INIT COMMAND TO */

/* INITIALIZE SPICE RESTART DATABASE */ /*------------------------------------*/

INIT DBDNAME(SPICHSAM) DEFAULTS SEGLEN(2030)

Utility 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 with 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

will issue a warning message when the program is run.


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.


The following 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

SPICERESTART(YES) 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.

SPICERESTART(NO) 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 will be selected in a

non-testing environment.


Exam ples


/* DISABLE AND ENABLE SPICE */ /* CONTROLLED RESTART */ /***** ****/


/*------------------------------------*/

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


The status of this option is shown by a text indicator in the formatted PSB entry report of


this report may be obtained. The indicator is as follows:

RESTART DISABLED Indicates that SPICE restart is disabled for this PSB. It is highly

unlikely that this option will 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 will accumulate in the SPICE Restart Database for PSBs

and jobs that are no longer run. Such entries can be deleted from the tables with the

SPICE operator facilities.

By default, SPICE will not delete entries for PSBs and jobs that are active. It does,

however, include options for deleting such entries. Incorrect use of this option can cause

catastrophic application program failure.


taken with this

command!


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.



The following diagram defines the DELETE command:

>>--- DELETE --- DBDNAME --- ( --- name --- ) ------------------------------>

>--------------- PSBNAME --- ( --- name --- ) ------------------------------>

>-----------.------------------------------------.-------------------------->

+--- JOBNAME --- ( -.- name -.- ) ---+ +- ALL --+

>----------------.-----------.---------------------------------------------->< +-- PURGE --+

Utility Diagram 5.18: DELET E command

PURGE If this keyword is present, SPICE will delete all selected

entries regardless of their restart status. Use with care !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.


taken with thisoption!



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.


The following diagram defines the DELETE command when 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

MSDBINDEX Identifies which entry in the database is to be flagged as

available for allocation. SPICE will 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 with discretion.

Exam ples

/*------------------------------------*/ /* EXAMPLES OF DELETE COMMANDS */

/* AGAINST MSDB ENTRIES */ /* */ /***** ****/


/*------------------------------------*/

DELETE DBDNAME(SPICMSAM) /* FREE UP ACTIVE ENTRY */ -

MSDBINDEX(0023) /* (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 when requested by Span

Software support staff.


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.



The following diagram defines the command that provides this option, the SET command:

>>--- SET --- DEBUG --- ( -.- NO --.- ) ------------------------------------> +- YES -+

Utility Diagram 5.20: SET diagnost ic command

DEBUG(NO) The SPICE utility program will continue processing after receiving

an invalid PCB status code. This is the default.

DEBUG(YES) The SPICE utility program will abend after receiving an invalid PCB

status code.

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 diagnost ic option


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


>--------------- 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 - ) ----->


>--------------- RESTARTLIMIT --- ( --- value --- ) ------------------------>

>--------------- BRAKING -- ( --- TIME -- ( - value - , - value - ) --- ) -->

>--------------- OUTOFSYNCTERM -- ( -.- KEEPRESTART -.- ) ------------------><

+- ABEND -------+



>--------------- DEFAULTS -------------------------------------------------->

>--------------- COMMIT --- ( --- TIME ----- ( - value - , - value - ) ----->


>--------------- TIMEOUT -- ( -.- WTO ---.---------------------------------->

+- WTOR --+ +- ABEND -+

>-------------------------------- TIME ----- ( - value - , - value - ) ----->


>--------------- RESTARTLIMIT --- ( --- value --- ) ------------------------>

>--------------- BRAKING -- ( --- TIME -- ( - value - , - value - ) --- ) -->

>--------------- OUTOFSYNCTERM -- ( -.- KEEPRESTART -.- ) ------------------>< +- ABEND -------+


>--------------- 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 -----+


INIT Command


>------------- DEFAULTS ---------------------------------------------------->

>----------------- SEGLEN --- ( -- value -- ) ------------------------------><


>------------- 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 -+

Migrat ing from Previous Versions 13118 June 2009 © 1993,2009 Span Software Consultants Limited

Appendix A. Migrating fromPrevious 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 with 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 with applications in a z/OS LE conforming manner.

SPAN recommend the following:

• Applications that do not use the SPICE LE Exit must be executed with 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.


• Programs including the SPICE LE User Exit will 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 following 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 was used as an alternative to CHKP, that would always result in

an IMS checkpoint. It is replaced by a double checkpoint.

SPICE SAM Pseudo-PCBs

SPICE Application programs can define their own SPICE SAM PCBs, in working

storage. Note, however, that SPICE DL/I also supports AIB control blocks, even when

no GSAM PCB exists. This standard technique of IMS achieves the same objective as

pseudo-PCBs. If users wish 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 fullword prefix, the first

halfword of which contained the length. To execute programs written in this non-

standard manner required that local modifications be made to SPICE. SPICE DL/I

includes the following option for supporting such programs.


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.



The following 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 recordprocessing

SSAM(NONSTANDARD) For programs that use this PSB, SPICE will

communicate variable record length with a full word

prefix, the length being contained in the first halfword.

SSAM(STANDARD) For programs that use this PSB, SPICE will communicate

variable record length in the standard GSAM manner, with a

half word prefix containing the length. This is the default.

Exam ples


/* CONTROL PROCESSING OF VARIABLE */ /* LENGTH RECORDS. */ /*------------------------------------*/

CHANGE DBDNAME(SPICHSAM) PSBNAME(SPIVP4CP) /* I.E. USE NON-STANDARD */ -

SSAM(NONSTANDARD) /* FULLWORD PREFIX */

CHANGE DBDNAME(SPICHSAM) /* I.E. USE GSAM STANDARD */ -

PSBNAME(SPIVP4CP) /* HALFWORD PREFIX */ - SSAM(STANDARD))

Utility Example A.1: CHANGE command for controlling variable record lengthprocessing





NONSTANDARD SSAM Indicates that SPICE will communicate variable record

length with a non-standard fullword prefix, for programs that

use this PSB. Absence of this text indicates that SPICE will

conform to the GSAM standard.

SPICE Utility Commands

SPICE 3.1 supports all previous dialects of the SPICE Utility Program command syntax.


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 following 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 Dif ferent 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 allowed 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 will continue to be

processed as before, and the command options for the feature are also supported.





ANY RESTART JOB NAME Indicates that a program using this PSB may be restarted

with a different job name. Absence of this text indicates

that the same job name is required.


IMS Checkpointing using SYNC Function Code

Earlier versions of SPICE included an option for selecting whether the CHKP or SYNC

function code would be used when SPICE issued an IMS checkpoint, when running as a

BMP. The SYNC function code is now always used for BMP checkpoints.


Glossary 13718 June 2009 © 1993,2009 Span Software Consultants Limited

GlossaryACB. 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.

AIB. The Application Interface Block, an

IMS control block. IMS application

programs can communicate DL/I requests

using an AIB, instead of a PCB.

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.

backout. The process by which an

application program's uncommitted

database updates are abandoned.

bind. The DB2 process whereby DBRMs

created by the DB2 precompiler are bound

together with 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 between an application

program and the DB2 system.

CASE. Computer Assisted Systems

Engineering.

CICS. Customer Information Control

System. An IBM transaction manager.

checkpoint. 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.

checkpoint braking. A SPICE technique

for reducing the rate at which an

application program consumes resources.

checkpoint suppression. A SPICE

technique for controlling the frequency of

checkpoints from application program

programs.

column. The vertical component of an

SQL database table.

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 braking. A SPICE

technique for reducing the rate at which 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 Software

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.

DBD. The Database Definition, an IMS

control block. Each IMS database is

defined to IMS with a DBD.

DBMS. Database Management System,

e.g. DB2 or IMS.

DBRM. Database Request Module. An

object created by the DB2 precompiler.


DBRMs are bound together to create an

application plan.

DD name . The label assigned to a z/OS

JCL DD statement.

DD statement. An z/OS JCL dataset

definition statement.

deadlock . The name given to the situation

when 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 whilst 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 checkpoint. 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.

GSAM. Generalized Sequential Access

Method, the means by which IMS

application programs can access sequential

files with DL/I requests.

HDAM. Hierarchical Direct Access

Method, a type of IMS DL/I database.

hexadecimal dump. A report of the

contents of an area of storage, presented in

hexadecimal digits (0-9,A-F).

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 own 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.

JES. Job Entry System. The z/OS job

management system.

Glossary 13918 June 2009 © 1993,2009 Span Software Consultants Limited

MPP. Message Processing Program. An

interactive IMS transaction program that

executes under the control of an IMS

DBCTL.

MSDB. Main Storage Database, a type of

IMS fast path database.

OS sequential files. z/OS disk or tape

files, that are processed in physical

sequence.

package. 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, which

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, where all

processing is repeated.

restart. Execution of an application

program after a failure, where only

processing performed after the last commit

point is repeated.

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.

restart database. The database where

SPICE keeps information relating to its

restartable programs.

rollback . The process by which 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

software.

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

which 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

between an application program and DB2.

SQLCODE. A field in the SQLCA control

block.

SQLERRM. A field in the SQLCA

control block.


status code. A field in each PCB, that IMS

uses to communicate error conditions.

symbolic checkpoint/restart. An IMS

facility for implementing restartable


sysmod. SMP/E System Modification.

table. A component in an SQL database.

Tables consist of columns and rows.

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.

Documents

SPICE DB2 & IMS Product Description - Span Software · operation of restartable batch application programs in the IMS environment. ... (CHKP & CCHK Function Codes) ... (OPEN Function