Download SPICE DL/I Product Reference Manual

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