T l Workload Scheduler Applications - Ordonnancement ...ordonnancement.org/pdf_c3212785.pdf · Tivoli ® Workload Scheduler for Applications User’s Guide Version 8.4 (Revised June

Tivoli® Workload Scheduler for Applications

User’s Guide

Version 8.4 (Revised June 2008)

SC32-1278-05

��

Tivoli® Workload Scheduler for Applications

User’s Guide

Version 8.4 (Revised June 2008)

SC32-1278-05

��

Note

Before using this information and the product it supports, read the information in “Notices” on page 317.

This edition applies to version 8, release 4, Fix Pack 1 of IBM Tivoli Workload Scheduler for Applications (program

number 5698-WSE) and to all subsequent releases and modifications until otherwise indicated in new editions.

This edition replaces SC32-1278-04.

© Copyright International Business Machines Corporation 2003, 2008. All rights reserved.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract

with IBM Corp.

Contents

Figures . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . ix

About this publication . . . . . . . . xi

What is new in this release . . . . . . . . . xi

What is new in this publication . . . . . . . . xi

Who should read this publication . . . . . . . xiii

What this publication contains . . . . . . . . xiii

Publications . . . . . . . . . . . . . . xv

Accessibility . . . . . . . . . . . . . . xv

Tivoli technical training . . . . . . . . . . xvi

Support information . . . . . . . . . . . xvi

How to read syntax diagrams . . . . . . . . xvi

Part 1. Common installation and

configuration tasks . . . . . . . . . 1

Chapter 1. Product overview . . . . . . 3

Chapter 2. Installing, upgrading, and

uninstalling IBM Tivoli Workload

Scheduler for Applications . . . . . . 5

Planning installation . . . . . . . . . . . . 5

Supported operating systems . . . . . . . . 5

Software prerequisites . . . . . . . . . . 6

Installation prerequisites . . . . . . . . . 6

The installation CDs . . . . . . . . . . . 8

Support for Internet Protocol version 6 . . . . 9

Before installing . . . . . . . . . . . . 9

Installing . . . . . . . . . . . . . . . 10

Installing Tivoli Workload Scheduler for

Applications using the launchpad . . . . . . 10


Applications using the ISMP installation wizard . 11

Installing the language pack using the ISMP

installation wizard . . . . . . . . . . . 13


Applications using the silent installation . . . . 14

Installing the language pack using silent

installation . . . . . . . . . . . . . 17

Installing IBM Tivoli Workload Scheduler for

Applications using Tivoli Software Distribution,

version 4.1 or Tivoli Configuration Manager,

version 4.2 or later . . . . . . . . . . . 19

Installing IBM Tivoli Workload Scheduler for

Applications using twsappsinst . . . . . . . 26

Installing the language pack using twsappsinst 28

Completing the installation of the access method

for Oracle E-Business Suite . . . . . . . . 31

Upgrading . . . . . . . . . . . . . . . 33

Upgrading Tivoli Workload Scheduler for

Applications using the ISMP installation wizard . 33


Applications using the silent installation . . . . 34


Applications using Tivoli Configuration Manager . 34


Applications using twsappsinst . . . . . . . 35

Uninstalling . . . . . . . . . . . . . . 36

Before uninstalling . . . . . . . . . . . 37

Uninstalling the language pack using ISMP

wizard . . . . . . . . . . . . . . . 38

Uninstalling Tivoli Workload Scheduler for

Applications using ISMP wizard . . . . . . 38


Applications or its language pack using Tivoli

Configuration Manager . . . . . . . . . 39

Uninstalling the language pack using silent

uninstallation . . . . . . . . . . . . . 39


Applications using silent uninstallation . . . . 40

Uninstalling IBM Tivoli Workload Scheduler for

Applications and its language pack using

twsappsinst . . . . . . . . . . . . . 40

Completing the removal of the access method for

Oracle E-Business Suite . . . . . . . . . 41

Chapter 3. Setting options with the

Option Editor . . . . . . . . . . . . 43

Option value inheritance . . . . . . . . . . 44

Using the Option Editor . . . . . . . . . . 44

Modifying local or global options files . . . . 46

Creating local options files . . . . . . . . 46

Chapter 4. Defining extended agent

workstations . . . . . . . . . . . . 47

Creating a workstation using the Job Scheduling

Console . . . . . . . . . . . . . . . . 47

Creating a workstation using the command line . . 50

Defining workstations for end-to-end scheduling . . 51

Creating the CPUREC statement . . . . . . 51

Defining the workstation with ISPF . . . . . 52

Chapter 5. Defining extended agent

jobs . . . . . . . . . . . . . . . . 53

Defining jobs with the Job Scheduling Console . . 53

General page . . . . . . . . . . . . . 54

Task page . . . . . . . . . . . . . . 56

Defining jobs using the Tivoli Workload Scheduler

command line . . . . . . . . . . . . . 57

Defining jobs for end-to-end scheduling . . . . . 57

Submitting extended agent jobs . . . . . . . . 58

Part 2. Oracle E-Business Suite

access method . . . . . . . . . . 59

© Copyright IBM Corp. 2003, 2008 iii

||

|||

Chapter 6. Introducing Tivoli Workload

Scheduler for Applications for Oracle

E-Business Suite . . . . . . . . . . 61

Software requirements . . . . . . . . . . . 61

Features . . . . . . . . . . . . . . . 61

Roles and responsibilities . . . . . . . . . . 61

Interface software . . . . . . . . . . . . 62

Chapter 7. Configuring the Oracle

E-Business Suite access method . . . 63

Defining the configuration options . . . . . . . 63

Examples . . . . . . . . . . . . . . 65

Encrypting Oracle E-Business Suite user

passwords . . . . . . . . . . . . . . 66

Chapter 8. Defining Oracle E-Business

Suite jobs . . . . . . . . . . . . . 67

Defining jobs in Oracle E-Business Suite . . . . . 67

Running a single job concurrently . . . . . . 67

Defining Oracle E-Business Suite jobs in Tivoli

Workload Scheduler . . . . . . . . . . . 67

Task string parameters for Oracle E-Business

Suite jobs . . . . . . . . . . . . . . 67

Tivoli Workload Scheduler and Oracle E-Business

Suite job states . . . . . . . . . . . . . 69

Part 3. PeopleSoft access method 71

Chapter 9. Introducing Tivoli Workload

Scheduler for Applications for

PeopleSoft . . . . . . . . . . . . . 73


Features . . . . . . . . . . . . . . . 73


Scheduling process for the PeopleSoft extended

agent . . . . . . . . . . . . . . . . 74

PeopleSoft job tracking in Tivoli Workload

Scheduler . . . . . . . . . . . . . . . 74

Security . . . . . . . . . . . . . . . 74

Chapter 10. Configuring the PeopleSoft

access method . . . . . . . . . . . 75

Defining the configuration options . . . . . . . 75

PeopleSoft options file example . . . . . . . 77

Connecting to more than one PeopleSoft

application server . . . . . . . . . . . 77

Creating a batch processing ID in PeopleSoft . . . 78

Configuring the ITWS_PSXA PeopleSoft project . . 78

Uploading the PeopleSoft project . . . . . . . 79

Chapter 11. Defining PeopleSoft jobs 83

Defining Peoplesoft jobs in Tivoli Workload

Scheduler . . . . . . . . . . . . . . . 83

Task string parameters for PeopleSoft jobs . . . 83

Configuring the job status mapping policy . . . . 85

Part 4. SAP R/3 access method . . . 87

Chapter 12. Introducing Tivoli

Workload Scheduler for Applications

for SAP . . . . . . . . . . . . . . 89


Features . . . . . . . . . . . . . . . 90

Scheduling process for the SAP extended agent . . 91


Unicode support . . . . . . . . . . . . . 93

What is Unicode . . . . . . . . . . . . 93

Unicode support on r3batch . . . . . . . . 93

Chapter 13. Configuring the SAP R/3

environment . . . . . . . . . . . . 95

Overview . . . . . . . . . . . . . . . 95

Creating the IBM Tivoli Workload Scheduler RFC

user . . . . . . . . . . . . . . . . . 95

Creating the authorization profile for the Tivoli

Workload Scheduler user . . . . . . . . . . 95

Using Transaction SU02 and manually creating

the profile . . . . . . . . . . . . . . 96

Using Transaction PFCG (Profile Generator) . . 96

Copying the correction and transport files . . . . 98

Importing ABAP/4 function modules into SAP R/3 98

Changing the Tivoli Workload Scheduler RFC user

ID password . . . . . . . . . . . . . 101

Migrating from previous versions . . . . . . 101

Print parameter and job class issues . . . . . . 102

Chapter 14. Configuring the SAP R/3

access method . . . . . . . . . . . 103

Defining the configuration options . . . . . . 103

Defining the global options . . . . . . . . 103

Defining the local options . . . . . . . . 105

Defining the common options . . . . . . . 106

SAP R/3 option file example . . . . . . . 111

Encrypting SAP R/3 user passwords . . . . 111

Configuration options usage . . . . . . . . 111

Connecting to the SAP system . . . . . . . . 112

Connecting to a specific application server . . 112

Connecting to a logon group . . . . . . . 113

Chapter 15. Managing the running of

SAP jobs . . . . . . . . . . . . . 115

Defining a job that runs an SAP job . . . . . . 115

General page . . . . . . . . . . . . 116

Task page . . . . . . . . . . . . . . 118

Managing SAP variants using the Job

Scheduling Console . . . . . . . . . . 126

Editing a standard SAP job . . . . . . . . . 128

Task string to define SAP jobs . . . . . . . . 129

Rerunning an SAP job . . . . . . . . . . 137

Rerunning a standard SAP job . . . . . . . 137

Rerunning a process chain job . . . . . . . 138

Chapter 16. Managing SAP jobs . . . 141

Displaying details about a standard SAP job . . . 141

Displaying details about a process chain job . . . 142

Verifying the status of a standard SAP job . . . . 144

iv IBM Tivoli Workload Scheduler for Applications: User’s Guide

||

||

1 1

| |

1 1

1 1

Deleting a standard SAP job from the SAP

database . . . . . . . . . . . . . . . 144

Balancing SAP workload using server groups . . 144

Mapping between Tivoli Workload Scheduler and

SAP job states . . . . . . . . . . . . . 145

Raising an SAP event . . . . . . . . . . . 145

Killing an SAP job instance . . . . . . . . . 147

Chapter 17. Defining SAP jobs

dynamically . . . . . . . . . . . . 149

Task string to define SAP jobs dynamically . . . 150

Defining attributes for ABAP steps . . . . . 156

Defining attributes for external programs and

external commands steps . . . . . . . . 159

Specifying job parameters using variable

substitution . . . . . . . . . . . . . . 160

Dynamically defining and updating SAP jobs:

some examples . . . . . . . . . . . . . 160

Chapter 18. Using Business

Information Warehouse . . . . . . . 163

Business Warehouse components . . . . . . . 163

Defining user authorizations to manage SAP R/3

Business Warehouse InfoPackages and process

chains . . . . . . . . . . . . . . . . 164

Managing SAP R/3 Business Warehouse

InfoPackages and process chains . . . . . . . 164

Creating a Tivoli Workload Scheduler job that

contains InfoPackages or process chains . . . 164

Displaying details about Business Warehouse

InfoPackages . . . . . . . . . . . . 169

Task string to define Business Warehouse

InfoPackages and process chains . . . . . . 169

Chapter 19. Using the BDC Wait

option . . . . . . . . . . . . . . 173

Chapter 20. Job interception and

parent-child features . . . . . . . . 175

Job interception . . . . . . . . . . . . 175

Implementing job interception . . . . . . . 175

The parent-child feature . . . . . . . . . . 180

Chapter 21. Exporting SAP R/3 factory

calendars . . . . . . . . . . . . . 181

Business scenario . . . . . . . . . . . . 181

Using the r3batch export function . . . . . . 181

Chapter 22. Defining internetwork

dependencies and event rules based

on SAP R/3 events . . . . . . . . . 185

Defining internetwork dependencies based on SAP

events . . . . . . . . . . . . . . . . 185

Committing SAP events by an external task . . 187


events with the Job Scheduling Console . . . . 188

Defining event rules based on SAP events . . . . 189

Prerequisite to defining event rules based on

SAP . . . . . . . . . . . . . . . 190

Monitoring SAP events . . . . . . . . . 190

Setting a filter for SAP events in the security file 192

Chapter 23. Defining event rules

based on IDoc records . . . . . . . 195

Business scenario . . . . . . . . . . . . 195

Creating event rules based on IDocs . . . . . . 196

Events matching criteria . . . . . . . . . 196

Examples of event rules based on IDocs . . . . 201

Chapter 24. National Language

support . . . . . . . . . . . . . . 203

Setting National Language support options . . . 203

SAP R/3 supported code pages . . . . . . . 204

Supported configurations and limitations . . . . 204

Part 5. z/OS access method . . . . 205

Chapter 25. Introducing Tivoli


for z/OS . . . . . . . . . . . . . . 207

Software requirements . . . . . . . . . . 207

Features . . . . . . . . . . . . . . . 207

Roles and responsibilities . . . . . . . . . 208

Installing, configuring, and uninstalling the z/OS

gateway . . . . . . . . . . . . . . . 208

Installing . . . . . . . . . . . . . . 208

Configuring . . . . . . . . . . . . . 210

Uninstalling . . . . . . . . . . . . . 211

Additional information . . . . . . . . . . 212

Gateway software components . . . . . . 212

IEFU84 Exit . . . . . . . . . . . . . 212

Security . . . . . . . . . . . . . . 212

Console Security . . . . . . . . . . . 213

Startup . . . . . . . . . . . . . . 213

SYSTSIN variables . . . . . . . . . . . 213

z/OS gateway version . . . . . . . . . 217

Downloading z/OS gateway fixes from FTP . . . 218

Locating product support . . . . . . . . . 220

Chapter 26. Configuring the z/OS

access method . . . . . . . . . . . 221

Defining the configuration options . . . . . . 221

Defining jobs in z/OS . . . . . . . . . . 222

Defining z/OS jobs in Tivoli Workload Scheduler 223

Task definition syntax for z/OS jobs scheduled

with Tivoli Workload Scheduler . . . . . . 223

Task definition syntax for other z/OS jobs . . . 225

Operational considerations for the EEWSERVE

gateway task . . . . . . . . . . . . 226

File (OPENS) dependencies syntax on z/OS files 227

Chapter 27. Reference information 229

Technical overview . . . . . . . . . . . 229

Managing JES jobs . . . . . . . . . . . 229

Managing CA-7 jobs . . . . . . . . . . 231

Contents v

||

11

|||||||

||||||||||||||

| | | | | | |

1 1 1 1 1 1 1 1 1 1 1

| |

Managing Tivoli Workload Scheduler for z/OS

jobs . . . . . . . . . . . . . . . 232

Checking for files on z/OS . . . . . . . . 234

Timing considerations . . . . . . . . . 234

Diagnostic information . . . . . . . . . . 235

Troubleshooting . . . . . . . . . . . . 235

Part 6. Common serviceability . . . 237

Chapter 28. The return code mapping

feature . . . . . . . . . . . . . . 239

Creating a return code mapping file . . . . . . 239

Syntax . . . . . . . . . . . . . . . 239

Examples . . . . . . . . . . . . . . 240

Considerations . . . . . . . . . . . . 240

Return code mapping for psagent and

MCMAGENT . . . . . . . . . . . . . 241

Examples . . . . . . . . . . . . . . 242

Return code mapping for r3batch . . . . . . . 242

Return code mapping file names for r3batch . . 244

Mapping return codes for intercepted jobs . . . 245

Chapter 29. Configuring the tracing

utility . . . . . . . . . . . . . . . 247

Customizing the .properties file . . . . . . . 247

Configuration file example for the SAP access

method . . . . . . . . . . . . . . . 249

Chapter 30. Troubleshooting . . . . . 251

Known installation problems . . . . . . . . 251

Other known problems . . . . . . . . . . 257

Troubleshooting the SAP R/3 connection . . . . 261

Chapter 31. Messages . . . . . . . . 263

IBM Tivoli message format . . . . . . . . . 263

Message number . . . . . . . . . . . 263

Message text . . . . . . . . . . . . 265

Message help . . . . . . . . . . . . 265

twsappsinst installation messages - AI . . . . . 266

z/OS gateway messages - I . . . . . . . . . 270

PeopleSoft access method messages - N . . . . 276

SAP R/3 access method messages - O . . . . . 278

Oracle access method messages - P . . . . . . 313

PeopleSoft access method messages - HTWGT . . 314

Notices . . . . . . . . . . . . . . 317

Notices and information . . . . . . . . . . 318

Libmsg . . . . . . . . . . . . . . . 319

Apache Jakarta ORO . . . . . . . . . . . 319

ISMP Installer (InstallShield 10.50x) . . . . . . 320

JXML CODE . . . . . . . . . . . . . . 320

InfoZip CODE . . . . . . . . . . . . . 321

HSQL Code . . . . . . . . . . . . . . 322

HP-UX Runtime Environment, for the Java(tm) 2

Platform . . . . . . . . . . . . . . . 323

Trademarks . . . . . . . . . . . . . . 327

Index . . . . . . . . . . . . . . . 329

vi IBM Tivoli Workload Scheduler for Applications: User’s Guide

Figures

1. How extended agents work . . . . . . . 4

2. Welcome page . . . . . . . . . . . . 11

3. The Option Editor . . . . . . . . . . 45

4. Defining a workstation using the Job

Scheduling Console . . . . . . . . . . 48

5. Defining an Extended Agent workstation 52

6. The General Page of the Properties - Job

Definition panel . . . . . . . . . . . 54

7. The Task Page of the Properties - Job


8. Defining an Extended Agent job for end-to-end

scheduling . . . . . . . . . . . . . 58

9. The General page of the Properties - Job


10. The Task page of the Properties - Job


11. The SAP Job Definition panel . . . . . . 121

12. The Steps page of the SAP Job Definition

panel . . . . . . . . . . . . . . 123

13. The Print Parameter Flags panel . . . . . 125

14. The Variant List panel . . . . . . . . 126

15. The Variant Information page of the Variant

List panel . . . . . . . . . . . . . 127

16. Tivoli Dynamic Workload Console - Table of

results . . . . . . . . . . . . . . 142

17. Tivoli Dynamic Workload Console - Details of

a process chain job . . . . . . . . . . 143

18. The Raise Event panel . . . . . . . . 146

19. The General page of the Properties - Job


20. The SAP Pick List panel . . . . . . . . 167

21. The SAP Pick List panel . . . . . . . . 168

22. The Table Criteria panel . . . . . . . . 177



25. Managing high priority IDocs overview 195

© Copyright IBM Corp. 2003, 2008 vii

||

1 1 1 1 1 1

| | | | 1 1

viii IBM Tivoli Workload Scheduler for Applications: User’s Guide

Tables

1. Supported operating systems . . . . . . . 5

2. Disk space requirements in megabytes . . . . 7

3. ISMP temporary space requirements in

megabytes . . . . . . . . . . . . . 7

4. Installation CDs for IBM Tivoli Workload

Scheduler for Applications . . . . . . . . 8

5. Options required for silent installation . . . 15

6. Options for the language pack silent

installation . . . . . . . . . . . . . 18

7. List of software package blocks to install IBM

Tivoli Workload Scheduler for Applications . . 19

8. Software package block to install IBM Tivoli

Workload Scheduler for Applications language

pack . . . . . . . . . . . . . . . 22

9. Options to install Tivoli Workload Scheduler

for Applications using SPBs . . . . . . . 22

10. Options to install the language packs using

SPBs . . . . . . . . . . . . . . . 23

11. twsappsinst parameters to install IBM Tivoli

Workload Scheduler for Applications . . . . 27

12. twsappsinst parameters to install IBM Tivoli

Workload Scheduler for Applications language

pack . . . . . . . . . . . . . . . 29

13. Options required for silent upgrade . . . . 34

14. twsappsinst parameters to upgrade IBM Tivoli


15. twsappsinst parameters to uninstall IBM Tivoli


16. How to complete the fields of the Properties -

Workstation in Database panel . . . . . . 49

17. Roles and responsibilities in Tivoli Workload

Scheduler for Applications for Oracle

E-Business Suite . . . . . . . . . . . 61

18. MCMAGENT access method options . . . . 63

19. Task string parameters for Oracle E-Business

Suite jobs . . . . . . . . . . . . . 68

20. Tivoli Workload Scheduler and Oracle

E-Business Suite job states . . . . . . . 69


Scheduler for Applications for PeopleSoft . . 73

22. Psagent access method options . . . . . . 75

23. Task string parameters for PeopleSoft jobs 84

24. Relationship between the run status, the

distribution status, and the Tivoli Workload

Scheduler job status . . . . . . . . . . 85

25. Relationship between the run status and the

Tivoli Workload Scheduler job status . . . . 86

26. SAP R/3 support packages . . . . . . . 89

27. SAP Business Warehouse support packages 90

28. Tivoli Workload Scheduler for Applications for

SAP features . . . . . . . . . . . . 90


Scheduler for Applications for SAP . . . . 91

30. ABAP/4 modules . . . . . . . . . . 100

31. r3batch global configuration options . . . . 103

32. r3batch local configuration options . . . . 105

33. r3batch common configuration options 106

34. Placeholders and counters for extended

variants . . . . . . . . . . . . . 127

35. Task string parameters for SAP jobs . . . . 131

36. Actions performed when you rerun a process

chain job . . . . . . . . . . . . . 138

37. Status transitions in Tivoli Workload

Scheduler (internal status) and the

corresponding SAP R/3 status . . . . . . 145

38. Task string parameters for SAP jobs (dynamic

definition) . . . . . . . . . . . . 152

39. Supported attributes for ABAP step definition 156

40. Supported attributes for external programs

and external commands step definition . . . 159

41. Task string parameters for SAP R/3 jobs 170

42. Placeholders for job interception template

files . . . . . . . . . . . . . . . 179

43. Parameters to define an SAP internetwork

dependency . . . . . . . . . . . . 186

44. Internetwork dependency definition and

possible resolution . . . . . . . . . . 187

45. History table of the SAP events raised 191

46. SAP event matching with the event rule

defined . . . . . . . . . . . . . 191

47. History table of the SAP events raised 192

48. SAP events matching with the event rule

defined . . . . . . . . . . . . . 192

49. Tivoli Workload Scheduler fields used to

define event rules . . . . . . . . . . 196

50. Tivoli Workload Scheduler fields used to

define correlation rules . . . . . . . . 197

51. Parameters of IDOCEventGenerated event

type . . . . . . . . . . . . . . . 198

52. Standard outbound IDoc statuses . . . . . 199

53. Standard inbound IDoc statuses . . . . . 200

54. SAP R/3 supported code pages . . . . . 204

55. Additional z/OS software requirements 207


Scheduler for Applications for z/OS . . . . 208

57. SYSTSIN variables . . . . . . . . . . 213

58. File characteristics for obtaining the gateway

fix pack files by FTP . . . . . . . . . 218

59. File characteristics for the LOADLIB file after

receiving it . . . . . . . . . . . . 219

60. File characteristics for the SAMPLIB file after

receiving it . . . . . . . . . . . . 220

61. Tivoli Workload Scheduler for Applications

for z/OS access method options . . . . . 222

62. JES job states with respect to Tivoli Workload

Scheduler . . . . . . . . . . . . . 229

63. CA-7 job states with respect to Tivoli

Workload Scheduler . . . . . . . . . 231

64. Tivoli Workload Scheduler for z/OS

operation states with respect to Tivoli

Workload Scheduler . . . . . . . . . 233

© Copyright IBM Corp. 2003, 2008 ix

||

||||

|||

11111|||

1 1 1

| | | | | | | | | | | | | | | | | | | 1 1 1 1 1 1 1 1 1 1 1 1 1

| | |

65. Tivoli Workload Scheduler for z/OS

operation occurrence states with respect to

Tivoli Workload Scheduler . . . . . . . 233

66. Job states and return codes for the Oracle

E-Business Suite access method . . . . . 241

67. Job states and return codes for the PeopleSoft

access method . . . . . . . . . . . 241

68. Known installation problems . . . . . . 251

69. Miscellaneous troubleshooting items . . . . 257

70. Tivoli Workload Scheduler for Applications

messages - component codes . . . . . . 263

71. z/OS module names . . . . . . . . . 270

x IBM Tivoli Workload Scheduler for Applications: User’s Guide

About this publication

The IBM Tivoli Workload Scheduler for Applications: User’s Guide provides information

about how to install, set up, and use the IBM® Tivoli® Workload Scheduler access

methods that run and control jobs of the following applications:

v Oracle E-Business Suite

v PeopleSoft

v SAP R/3

v z/OS®

What is new in this release

For information about the new and changed functions in this release, see Tivoli

Workload Scheduling Suite: Overview.

For information about the APARs that this release addresses, see the IBM Tivoli

Workload Scheduler for Applications Download Document at http://www.ibm.com/support/docview.wss?rs=673&uid=swg24017449.

What is new in this publication

This section describes what has changed in this publication since version 8.3 fix

pack 1.

Note: Changed or added text is marked in the left margin as follows:

v By a vertical bar, if the text was changed or added with respect to the

previous version.

v By the number of a fix pack, if the changed or added text applies only

after a particular fix pack is installed. For example, 1 to refer to Fix Pack

1, and so on.

Part 1. Common installation and configuration tasks

v The following operating systems are no longer supported:

– Compaq Tru64

– IBM Sequent Dynix

– SGI IRIXv Information about supporting Internet Protocol version 6 is provided in

“Support for Internet Protocol version 6” on page 9.

v Information about how to install the product using the launchpad is

provided in “Installing Tivoli Workload Scheduler for Applications using

the launchpad” on page 10.

v The procedure to complete the installation of the Oracle E-Business Suite

access method has been modified. For details, see “Completing the

installation of the access method for Oracle E-Business Suite” on page

31.

Part 2. Oracle E-Business Suite access method

v To help you identify the users' roles and tasks, a table that links roles

and responsibilities is provided in Table 17 on page 61.

Part 3. PeopleSoft access method

© Copyright IBM Corp. 2003, 2008 xi

1

11

111

|

|

|

|

||

|||

||||

||

http://www.ibm.com/support/docview.wss?rs=673&uid=swg24017449

http://www.ibm.com/support/docview.wss?rs=673&uid=swg24017449



Part 4. SAP R/3 access method

v Tivoli Workload Scheduler for Applications 8.4 is certified by SAP for

the following two SAP interfaces:

BW-SCH 3.0 - Scheduling for SAP BW 3.0

Certification Category: Business Information Warehouse, Job

Scheduling

Qualification: Certified for SAP NetWeaver

BW-XBP 6.10 - Background Processing, Job Scheduling 6.10 (Version

2.0)

Certification Category: Background Processing, Job Scheduling,

Scheduling, System Management

Qualification: Certified for SAP NetWeaver

Note: For detailed information, see the SAP online product partner

directory.



v You can control how Tivoli Workload Scheduler sets the completion

status of a job running BDC sessions, according to any BDC processing

failure. For details, see the bdc_job_status_failed option described in

“Defining the common options” on page 106.

v You can determine the action performed by Tivoli Workload Scheduler

when you rerun a job that submits a process chain. For details, refer to

“Rerunning a process chain job” on page 138.

v To display details about an SAP process chain that you ran as a Tivoli

Workload Scheduler job, see “Displaying details about a process chain

job” on page 142.

v You can assign a SAP R/3 job to a server group, for batch processing.

For details, see “Balancing SAP workload using server groups” on page

144.

v You can now export SAP R/3 factory calendars into an output file

compatible with the Tivoli Workload Scheduler composer and use it to

create or replace Tivoli Workload Scheduler calendars. For details, see

Chapter 21, “Exporting SAP R/3 factory calendars,” on page 181.

v To define an internetwork dependency or event rule based on SAP R/3

events, and to monitor and filter SAP R/3 events, refer to Chapter 22,

“Defining internetwork dependencies and event rules based on SAP R/3

events,” on page 185.

v You can monitor IDoc records and forward events to Tivoli Workload

Scheduler, to perform a specific action. For detailed information, refer to

Chapter 23, “Defining event rules based on IDoc records,” on page 195.

Part 3. z/OS access method



What is new

xii IBM Tivoli Workload Scheduler for Applications: User’s Guide

||

11

111

1

1111

1

11

||

1111

111

111

|||

||||

||||

111

||

Who should read this publication

This publication is intended for job schedulers who intend to run and control jobs

of the applications with IBM Tivoli Workload Scheduler. Users of this publication

should have some knowledge of:

v IBM Tivoli Workload Scheduler

v Tivoli Job Scheduling Console

v The specific application environment

What this publication contains

This publication contains the following sections:


Part 1 contains the following chapters:

v Chapter 1, “Product overview,” on page 3

describes the basic functions of an extended agent.

v Chapter 2, “Installing, upgrading, and uninstalling IBM Tivoli Workload

Scheduler for Applications,” on page 5

describes the various ways of installing, upgrading, and uninstalling the product

and its language pack, together with the operating systems it supports and its

prerequisites.

v Chapter 3, “Setting options with the Option Editor,” on page 43

describes how to use the Option Editor.

v Chapter 4, “Defining extended agent workstations,” on page 47

describes how to define extended agent workstations for all the access methods.

v Chapter 5, “Defining extended agent jobs,” on page 53

describes how to define extended agent jobs for all the access methods.



v Chapter 6, “Introducing Tivoli Workload Scheduler for Applications for Oracle

E-Business Suite,” on page 61

describes software requirements, features, users' roles and tasks, and interface

software specifically for the Oracle E-Business Suite access method.

v Chapter 7, “Configuring the Oracle E-Business Suite access method,” on page 63

describes how to configure the options used by the Oracle E-Business Suite

access method.

v Chapter 8, “Defining Oracle E-Business Suite jobs,” on page 67

describes how to define Tivoli Workload Scheduler jobs specifically for the

Oracle E-Business Suite access method.



v Chapter 9, “Introducing Tivoli Workload Scheduler for Applications for

PeopleSoft,” on page 73

describes software requirements, features, users' roles and tasks, and other

general information specific to the PeopleSoft access method.

Who should read this publication

About this publication xiii

v Chapter 10, “Configuring the PeopleSoft access method,” on page 75

describes how to configure the options used by the PeopleSoft access method.

v Chapter 11, “Defining PeopleSoft jobs,” on page 83

describes how to define Tivoli Workload Scheduler jobs specifically for the

PeopleSoft access method.



v Chapter 12, “Introducing Tivoli Workload Scheduler for Applications for SAP,”

on page 89

describes software requirements, features, users' roles and tasks, and Unicode

support for the SAP R/3 access method.

v Chapter 13, “Configuring the SAP R/3 environment,” on page 95

describes how to configure this access method for use with SAP R/3.

v Chapter 14, “Configuring the SAP R/3 access method,” on page 103

describes how to configure the options used by this access method.

v Chapter 15, “Managing the running of SAP jobs,” on page 115

describes how to define Tivoli Workload Scheduler jobs specifically for the SAP

R/3 access method.

v Chapter 16, “Managing SAP jobs,” on page 141

describes how you can work with SAP R/3 jobs, for example displaying details

about a job or balancing the workload among servers.

v Chapter 17, “Defining SAP jobs dynamically,” on page 149

describes how to create and submit SAP R/3 jobs instantly in the end-to-end

scheduling environment, without creating or referencing pre-defined job

templates.

v Chapter 18, “Using Business Information Warehouse,” on page 163

provides information on how to use the access method with the Business

Information Warehouse.

v Chapter 19, “Using the BDC Wait option,” on page 173

provides details on BDC wait option.

v Chapter 20, “Job interception and parent-child features,” on page 175

describes the Job interception and Parent-child features of XBP 2.0.

v Chapter 21, “Exporting SAP R/3 factory calendars,” on page 181

describes how to export SAP R/3 factory calendars so that they can be processed

by Tivoli Workload Scheduler, and how to add the exported calendar definitions

to the Tivoli Workload Scheduler database.

v Chapter 22, “Defining internetwork dependencies and event rules based on SAP

R/3 events,” on page 185

describes how to define internetwork dependencies and event rules for Tivoli

Workload Scheduler based on SAP R/3 events.

v Chapter 23, “Defining event rules based on IDoc records,” on page 195

describes how to define event rules for Tivoli Workload Scheduler based on IDoc

records.

v Chapter 24, “National Language support,” on page 203

describes national language support for this access method.



xiv IBM Tivoli Workload Scheduler for Applications: User’s Guide

1

11

|

|||

||

||

1

11


v Chapter 25, “Introducing Tivoli Workload Scheduler for Applications for z/OS,”

on page 207

provides software requirements, features, users' roles and tasks for the z/OS

access method. It also describes how to install the gateway component on z/OS.

v Chapter 26, “Configuring the z/OS access method,” on page 221

describes how to configure the options used by this access method and provides

method-specific information on defining jobs.

v Chapter 27, “Reference information,” on page 229

provides reference information for operating with the supported job schedulers

and lists gateway messages.

Part 6. Common serviceability


v Chapter 28, “The return code mapping feature,” on page 239

describes how to use the return code mapping utility.

v Chapter 29, “Configuring the tracing utility,” on page 247

describes how to configure the tracing utility.

v Chapter 30, “Troubleshooting,” on page 251

provides some general troubleshooting information.

v Chapter 31, “Messages,” on page 263

provides you with help on error and warning messages issued by:

– twsappsinst

– z/OS gateway

– PeopleSoft access method

– SAP R/3 access method

– Oracle E-Business Suite access method

Publications

Full details of Tivoli Workload Scheduler publications can be found in Tivoli

Workload Scheduling Suite: Publications. This document also contains information

about the conventions used in the publications.

A glossary of terms used in the product can be found in Tivoli Workload Scheduling

Suite: Glossary.

Both of these are in the Information Center as separate publications.

Accessibility

Accessibility features help users with a physical disability, such as restricted

mobility or limited vision, to use software products successfully. With this product,

you can use assistive technologies to hear and navigate the interface. You can also

use the keyboard instead of the mouse to operate all features of the graphical user

interface.

For full information with respect to the Job Scheduling Console, see the

Accessibility Appendix in the Tivoli Workload Scheduler: Job Scheduling Console User’s

Guide.


About this publication xv

For full information with respect to the Tivoli Dynamic Workload Console, see the

Accessibility Appendix in the Tivoli Workload Scheduler: User's Guide and Reference.

Tivoli technical training

For Tivoli technical training information, refer to the following IBM Tivoli

Education Web site:

http://www.ibm.com/software/tivoli/education

Support information

If you have a problem with your IBM software, you want to resolve it quickly. IBM

provides the following ways for you to obtain the support you need:

v Searching knowledge bases: You can search across a large collection of known

problems and workarounds, Technotes, and other information.

v Obtaining fixes: You can locate the latest fixes that are already available for your

product.

v Contacting IBM Software Support: If you still cannot solve your problem, and

you need to work with someone from IBM, you can use a variety of ways to

contact IBM Software Support.

For more information about these three ways of resolving problems, see the

Appendix about support information in Tivoli Workload Scheduler: Troubleshooting

Guide.

How to read syntax diagrams

Throughout this publication, syntax is described in diagrams like the one shown

here, which describes the SRSTAT command:

�� SRSTAT ' resource name '

OPCA

SUBSYS(

subsystem name

)

MSTR

�

� KEEP

AVAIL(

RESET

)

NO

YES

KEEP

DEVIATION(

amount

)

RESET

�

� KEEP

QUANTITY(

amount

)

RESET

YES

CREATE(

NO

)

�

� 0

TRACE(

trace level

)

��

The symbols have these meanings:

��─────

The statement begins here.

Accessibility

xvi IBM Tivoli Workload Scheduler for Applications: User’s Guide

http://www.ibm.com/software/tivoli/education

──────�

The statement is continued on the next line.

�──────

The statement is continued from a previous line.

─────��

The statement ends here.

Read the syntax diagrams from left to right and from top to bottom, following the

path of the line.

These are the conventions used in the diagrams:

v Required items appear on the horizontal line (main path):

�� STATEMENT required item ��

v Optional items appear below the main path:

�� STATEMENT

optional item ��

v An arrow returning to the left above the item indicates an item that you can

repeat. If a separator is required between items, it is shown on the repeat arrow.

��

STATEMENT

�

,

repeatable item

��

v If you can choose from two or more items, they appear vertically in a stack.

– If you must choose one of the items, one item of the stack appears on the

main path:

�� STATEMENT required choice 1

required choice 2 ��

– If choosing one of the items is optional, the entire stack appears below the

main path:

�� STATEMENT

optional choice 1

optional choice 2

��

– A repeat arrow above a stack indicates that you can make more than one

choice from the stacked items:

��

STATEMENT

�

,

optional choice 1

optional choice 2

optional choice 3

��

Support information

About this publication xvii

��

STATEMENT

�

,

required choice 1

required choice 2

required choice 3

��

v Parameters that are above the main line are default parameters:

��

STATEMENT default

alternative

��

v Keywords appear in uppercase (for example, STATEMENT).

v Parentheses and commas must be entered as part of the command syntax, as

shown.

v For complex commands, the item attributes might not fit on one horizontal line.

If that line cannot be split, the attributes appear at the bottom of the syntax

diagram:

�� STATEMENT required choice 1

option 1

option 2

required choice 2

required choice 3

��

option 1

default

optional choice 1(

alternative

)

option 2

default

optional choice 2(

alternative

)

Support information

xviii IBM Tivoli Workload Scheduler for Applications: User’s Guide


© Copyright IBM Corp. 2003, 2008 1

2 IBM Tivoli Workload Scheduler for Applications: User’s Guide

Chapter 1. Product overview

Extended agents (XA) are used to extend the job scheduling functions of IBM

Tivoli Workload Scheduler to other systems and applications. An extended agent is

defined as a workstation that has a host and an access method.

The host is a Tivoli Workload Scheduler fault-tolerant agent (FTA) or standard

agent (SA).

The access method is a program that is run by the hosting workstation whenever

Tivoli Workload Scheduler needs to interact with the external system either

through its command line or the Tivoli Job Scheduling Console. Tivoli Workload

Scheduler for Applications includes the following access methods:

v Oracle E-Business Suite (MCMAGENT)

v PeopleSoft (psagent)

v SAP R/3 (r3batch)

v z/OS (mvsca7, mvsjes, and mvsopc)

To launch and monitor a job on an extended agent, the host runs the access

method, passing it job details as command line options. The access method

communicates with the external system to launch the job and returns the status of

the job.

An extended agent workstation is a logical entity related to an access method

hosted by the physical Tivoli Workload Scheduler workstation (a fault-tolerant

agent or standard agent). More than one extended agent workstation can be hosted

by the same Tivoli Workload Scheduler workstation and rely on the same access

method. The extended agent is defined in a standard Tivoli Workload Scheduler

workstation definition, which gives the extended agent a name and identifies the

access method.

Figure 1 on page 4 shows how these elements fit together in the case of a typical

extended agent configuration.


|||||||

To launch a job in an external environment, Tivoli Workload Scheduler runs the

extended agent access method providing it with the extended agent workstation

name and information about the job. The method looks at the corresponding file

named WORKSTATIONNAME_methodname.opts to determine which external

environment instance it will connect to. The access method can then launch jobs on

that instance and monitor them through completion, writing job progress and

status information in the standard list file of the job.

Extended agents can also be used to run jobs in an end-to-end environment, where

their scheduling and monitoring is performed from an IBM Tivoli Workload

Scheduler for z/OS controller.

Figure 1. How extended agents work

Product overview


Chapter 2. Installing, upgrading, and uninstalling IBM Tivoli


This chapter describes how to install, upgrade, and uninstall Tivoli Workload

Scheduler for Applications and its language pack. It is divided into the following

sections:

v “Planning installation”

v “Installing” on page 10

v “Upgrading” on page 33

v “Uninstalling” on page 36

Planning installation

Refer to the following sections to plan your installation of Tivoli Workload

Scheduler for Applications:

v “Supported operating systems”

v “Software prerequisites” on page 6

v “Installation prerequisites” on page 6

v “The installation CDs” on page 8

v “Support for Internet Protocol version 6” on page 9

v “Before installing” on page 9

Supported operating systems

Table 1 lists the operating systems supported by Tivoli Workload Scheduler for

Applications, version 8.4:

Table 1. Supported operating systems

Operating System Access Method

z/OS (Gateway) z/OS

(Transaction

Server)

SAP R/3 PeopleSoft Oracle

E-Business Suite

Microsoft® Windows

Microsoft Windows 2000 U U U

Microsoft Windows 2003 U U U

Microsoft Windows XP

Professional

U U U

Microsoft Vista U U U

IBM AIX

IBM AIX version 5.2, 5.3, 5.4 U U U U

Sun Solaris Operating Environment

Sun Solaris Operating

Environment version 9, 10

U U U U


Environment for Opteron,

version 10

U U

HP-UX


||

||

||||

||||

|

||||||

||||||

|||||||

||||||

|

||||||

|

|||||||

|||

|||||

|

Table 1. Supported operating systems (continued)

Operating System Access Method

z/OS (Gateway) z/OS

(Transaction

Server)

SAP R/3 PeopleSoft Oracle

E-Business Suite

HP-UX version 11i v2, 11i v3

for PA-RISC

U U U U

HP-UX version 11i v2, 11i v3

for Integrity

U U U U

IBM OS/390®

IBM OS/390 V2R10 U

IBM z/OS

IBM z/OS version 1.8 U

Linux® on xSeries®

Red Hat Enterprise Linux

Advanced Server version 4.0,

5.0

U U U U

SuSE Linux Enterprise Server

version 9

U U U U


version 10

U U U

Linux on zSeries

Red Hat Enterprise Linux

Advanced Server version 4.0,

5.0

U U


version 9.0, 10.0

U U

Software prerequisites

Tivoli Workload Scheduler for Applications version 8.4 prerequisites Tivoli

Workload Scheduler version 8.2, or later.

Note: To define event rules based on SAP R/3 events with Tivoli Workload

Scheduler for Applications 8.4 Fix Pack 1, the master domain manager must

have Tivoli Workload Scheduler 8.4 Fix Pack 1, or later, installed.

Tivoli Workload Scheduler for Applications 8.4 interacts with the following

products:


v PeopleSoft

v SAP R/3

v z/OS

Installation prerequisites

Before you install the product, ensure that the following prerequisites are met:

v You have a working installation of Tivoli Workload Scheduler version 8.2, or

later, installed on your workstation.

v You have root permissions on UNIX and administrator permissions on Windows

to run the installation.

Supported operating systems


|

||

||||

||||

|||||||

|||||||

|

||||||

|

||||||

|

|||

|||||

|||||||

|||||||

|

|||

|||||

|||||||

|

111

v There are no scheduling activities currently running for the application you want

to install.

v There are no monitoring activities on SAP R/3 events currently running.

v For the access method for PeopleSoft, the corresponding PeopleSoft environment

is already installed and fully accessible from the workstation where you are

installing.

v For the access method for Oracle E-Business Suite, the Oracle E-Business Suite

server is already installed on the same physical node where the access method

and the Tivoli Workload Scheduler host resides.

v The installation process is not already running on the workstation. You can

verify this by running one of the following commands:

If you are installing using ISMP

ps -ef | grep setup.bin

If you are installing using twsappsinst

ps -ef | grep twsappsinst

v The Option Editor is not running.

v If you are installing using the ISMP both interactive and silent:

– The X Server is installed on a workstation in your environment.

– The X-windows Display is appropriately exported if you are launching the

installation process using a telnet session.v If you are installing the language pack, you have at least 10 MB of temporary

space available on your workstation.

v If you are installing the product on HP-UX version 11.0 using the ISMP

Installation Wizard, you set the maxdsiz kernel parameter to 0x06000000

hexadecimal (100663296).

v If you are installing the product, you have the disk space indicated in Table 2

and the temporary space indicated in Table 3.

Table 2. Disk space requirements in megabytes

Operating system Disk Space (MB)

z/OS SAP R/3 PeopleSoft Oracle

E-Business

Suite

Microsoft Windows 3MB 22MB 150MB

IBM AIX 3MB 22MB 150MB 1MB


Environment

3MB 23MB 1MB

HP-UX for PA-RISC 3MB 22MB 200MB 1MB

HP-UX for Integrity 3MB 22MB 200MB 1MB

Linux on xSeries 1MB 21MB 150MB 1MB

Linux on zSeries 4MB 11MB

Table 3 lists the temporary space required to install IBM Tivoli Workload

Scheduler for Applications using the ISMP installation method. The other

installation methods do not have any temporary space requirements.

Table 3. ISMP temporary space requirements in megabytes

Operating system ISMP temporary space (MB)

Microsoft Windows 200MB


Chapter 2. Installing, upgrading, and uninstalling IBM Tivoli Workload Scheduler for Applications 7

1

Table 3. ISMP temporary space requirements in megabytes (continued)

Operating system ISMP temporary space (MB)

IBM AIX 45MB

Sun Solaris Operating Environment 30MB

HP-UX for Integrity 300MB

HP-UX for PA-RISC 300MB

IBM z/OS

Linux on xSeries 45MB

Linux on zSeries 45MB

The installation CDs

Table 4 shows the CDs contained in IBM Tivoli Workload Scheduler for

Applications and the operating systems to which they apply.

Table 4. Installation CDs for IBM Tivoli Workload Scheduler for Applications

CD label Operating systems

IBM Tivoli Workload Scheduler for

Applications Installation CD 1

AIX and Microsoft Windows. It also includes

the following directories:

v LICENSE

v RESPONSE_FILE

v z/OS libraries for the specific operating

systems



Linux and Linux S390. It also includes the

following directories:

v LICENSE

v RESPONSE_FILE


systems



HP-UX for PA-RISC. It also includes the


v LICENSE

v RESPONSE_FILE


systems



Sun Solaris. It also includes the following

directories:

v LICENSE

v RESPONSE_FILE


systems



Sun Solaris for Opteron. It also includes the


v LICENSE

v RESPONSE_FILE


systems



HP-UX for Integrity. It also includes the


v LICENSE

v RESPONSE_FILE


systems



||||||||

||||||||

||||||||

Support for Internet Protocol version 6

IBM Tivoli Workload Scheduler for Applications, version 8.4, supports Internet

Protocol version 6 (IPv6) in addition to legacy IPv4. Support to IPv6 is provided

only on the z/OS extended agent with the following software requirements:

v IBM Tivoli Workload Scheduler version 8.4, or later

v TCP/IP for the z/OS system on IBM 3.1, or later

Before installing

Depending on the installation method you use, during the installation of Tivoli

Workload Scheduler for Applications you are asked to provide the following

information:

Regardless of the installation method you use

The name of the operating system user ID used to launch the access method

you are installing. For example, user1 for r3batch and user2 for psagent.

If you are installing using the ISMP silent installation, or using twsappsinst and

you want to specify an installation directory different from the IBM Tivoli

Workload Scheduler user home directory, or the ISMP wizard discovery process

does not detect any existing installation

The path of the IBM Tivoli Workload Scheduler installation where you want to

install Tivoli Workload Scheduler for Applications. For example,

/home/tws84/tws

If you are installing using the ISMP silent installation or if the ISMP wizard

discovery process does not detect any existing installation

A name for the installation of Tivoli Workload Scheduler for Applications. For

version 8.2 or later, it is the same as the TWSuser name. For example, TWS.


The TWSuser name. For example, TWS.

If you are installing PeopleSoft

The full path to the psjoa.jar file corresponding to the release of PeopleSoft you

are working with. For example, use the psjoa.jar file of PeopleSoft version 8.45

if you are working with version 8.45. To make the psjoa.jar file available on the

workstation where you are installing Tivoli Workload Scheduler for

Applications, do the following:

1. On the workstation where the PeopleSoft application is installed, locate the

ps_home\class\ psjoa.jar file.

2. Either copy the file to the workstation where you are installing Tivoli

Workload Scheduler for Applications or make it accessible by mapping the

path to the workstation where the PeopleSoft application is installed.

Note: The psjoa.jar path cannot contain special characters.

Support for IPv6


|

|||

|

|

Installing

By installing Tivoli Workload Scheduler for Applications, you install:

v One or more access methods to interact with the following products:

– Oracle E-Business Suite

For this access method, regardless of the installation procedure you choose,

you must complete the installation as described in “Completing the

installation of the access method for Oracle E-Business Suite” on page 31.

– PeopleSoft

– SAP R/3

– z/OSv The Option Editor, a graphical tool to help you configure your environment after

installation.

v Optionally, one or more Tivoli Workload Scheduler for Applications language

packs.

To install Tivoli Workload Scheduler for Applications and its language pack, you

can use any of the following procedures. You must install all the access methods

using the same installation procedure:

v The launchpad

v The InstallShield MultiPlatform (ISMP) wizard

v The ISMP silent installation

v The Tivoli Software Distribution, version 4.1 product or the Software

Distribution component of Tivoli Configuration Manager, version 4.2 or later

v On AIX, UNIX, HP-UX, Solaris, and Linux operating systems, the twsappsinst

command.

Installing Tivoli Workload Scheduler for Applications using the

launchpad

Use the launchpad if you want to be guided through a set of panels that help you

become familiar with the product documentation. From this user interface you can

access the following sources of information:

v Tivoli Workload Scheduler for Applications home page

v Tivoli Workload Scheduler for Applications Download Document

v Tivoli Workload Scheduler for Applications information center

v Tivoli Workload Scheduler for Applications support Web site

You can use the launchpad only with one of the following Web browsers:

v Mozilla

v Firefox

v Internet Explorer (for Windows operating systems, only)

The general procedure for starting the launchpad installation program is as

follows:

1. Insert the CD containing the installation image for your operating system into

the CD drive.

2. Depending on the operating system, start the launchpad:

On Windows The launchpad should start automatically. If not, from the root

directory of the CD, run the launchpad.exe file.

On UNIX From the root directory of the CD, run the launchpad.sh file.

Installing


|

||

||||||

||

||

|

|

|

|||

|

|

|

|

||||

||

||

|

|||

||

The launchpad opens:

3. Navigate the documentation and, when you are ready to start the installation

process, click Install IBM Tivoli Workload Scheduler for Applications in the

left frame of the page.

For details about how to continue the installation, refer to “Installing Tivoli

Workload Scheduler for Applications using the ISMP installation wizard.”


ISMP installation wizard

This section explains how to perform the following tasks using the ISMP

installation wizard:

v Install IBM Tivoli Workload Scheduler for Applications.

v Add an access method to an already existing installation of Tivoli Workload

Scheduler for Applications.

Using the ISMP installation wizard you also automatically install the Option

Editor. The Option Editor is a Java-based file editor that you use to define options

for the access methods you installed.

To install one or more access methods of Tivoli Workload Scheduler for

Applications, perform the following steps:

1. From the product CD for the operating system on which you are installing the

product, or from an image, run the setup installation command located in the

INSTALLER directory. The installation starts.

Note: If you decide to perform the installation from an image, ensure that the

path where you copy the images does not contains blanks and that you

maintain the CD directory structure.

Figure 2. Welcome page

Installing using the launchpad


|

|||

||

|||

||

2. Select the language in which you want the wizard to be displayed, and click

OK. The Welcome panel is displayed.

3. Read the welcome information and click Next. The Software License

Agreement panel is displayed.

4. Read the Software License Agreement information and select the radio button

to accept the license agreement. Click Next. The Select the Type of Installation

panel is displayed.

5. Select one of the following:

Install To install Tivoli Workload Scheduler for Applications. If you

select this option, click Next and proceed with step 6.

Add To add an access method to an already existing installation of

Tivoli Workload Scheduler for Applications. If you select this

option, click Next and proceed with step 7. Using this option

you can also repair a corrupted installation.

Upgrade To upgrade an already existing installation of Tivoli Workload

Scheduler for Applications version 8.2, 8.2.1, or 8.3 to version

8.4. See “Upgrading” on page 33 for a detailed description

about how to upgrade from version 8.2 or 8.2.1 to version 8.3. 6. If you select Install, the installation program detects and lists all the

installations of Tivoli Workload Scheduler version 8.2.x, 8.3, or 8.4 on your

workstation.

a. Select the IBM Tivoli Workload Scheduler installation where you want to

install IBM Tivoli Workload Scheduler for Applications version 8.4. If the

product does not detect any existing installation a panel is displayed

where you have to specify the name and the directory of another existing

installation. The installation name must be unique. For example, for the

name of the installation you can use the user name associated to the IBM

Tivoli Workload Scheduler installation.

b. Click Next. The installation program detects and lists all the features of

Tivoli Workload Scheduler for Applications that you can install on your

workstation.

Proceed with step 8.

7. If you select Add on the Select the type of installation panel, the installation

program detects and lists all the Tivoli Workload Scheduler for Applications

installations that already exist on your workstation.

Select the Tivoli Workload Scheduler for Applications installation where you

want to install the features and click Next. If the installation process does not

detect any installations, the following message is displayed:

The installation program did not find any

Tivoli Workload Scheduler for Applications installations.

Install Tivoli Workload Scheduler for Applications

before adding an access method.

Return to the previous panel and select Install.

In this case return to step 5 and select Install.

8. Select the access methods that you want to install on your workstation and

click Next. Depending on how many and which access methods you select,

one or more additional panels request specific access method information:

v For all access methods: the LJuser, that is the name as the operating system

user ID used to launch the selected method. This can be the same name of

Installing using ISMP installation wizard


the owner of the Tivoli Workload Scheduler installation, that is the user that

was defined when Tivoli Workload Scheduler was installed.

v For the PeopleSoft access method, the full path to the psjoa.jar file. See

“Before installing” on page 9 for detailed information. 9. Enter the requested information and click Next.

10. A summary information panel is displayed. Click Next. The installation

process begins to install the selected access methods on your workstation. The

installation progress panel is displayed showing the status of the installation.

11. When the installation has completed, a panel is displayed asking if you want

to open the Option Editor. The Option Editor is a Java-based file editor that

you use to define options for the access methods you installed. If you decide

not to run the Option Editor now, you can do it later. If you click Yes, the

Option Editor is displayed and you can set your options for the methods you

installed. See Chapter 3, “Setting options with the Option Editor,” on page 43

to learn how to use the Option Editor.

If you click No, or when you have finished with the Option Editor, the

installation exit window is displayed.

12. Click Finish to exit the installation wizard and complete the installation.

If you received error messages, analyze the /tmp/tws4apps_ismp.log and the

/tmp/TWS4APPS_installationname_accessmethod^8.4.log installation log files.

Note: On UNIX operating systems, if you want to install the language pack

after this installation, you need to log out and log in from the UNIX

shell before installing the language pack.

Installing the language pack using the ISMP installation wizard

This section describes how to perform the following tasks using the ISMP

installation wizard:

v Install the IBM Tivoli Workload Scheduler for Applications language pack.

v Add a language to an existing IBM Tivoli Workload Scheduler for Applications

language pack.

To install the IBM Tivoli Workload Scheduler for Applications language pack or

add a language to an existing language pack, perform the following steps:

1. Install Tivoli Workload Scheduler for Applications as described in “Installing

Tivoli Workload Scheduler for Applications using the ISMP installation

wizard” on page 11.

2. Verify that the TWS4APPS_JDKHOME environment variable is set to the

following path:

twsinstallationdir/methods/_tools

3. From the product CD for the operating system on which you are installing the

product, or from an image, run the setup installation command located in the

LANG_PACK directory. The installation starts.

Note: If you decide to perform the installation from an image ensure that the

path where you copy the images does not contains blanks and to

maintain the CD directory structure.





Installing using ISMP installation wizard



to accept the license agreement. Click Next. A panel listing the discovered IBM

Tivoli Workload Scheduler for Applications installations is displayed.

7. From the list of discovered IBM Tivoli Workload Scheduler for Applications

installations, select the installation where you want to install the language

pack.

Note: If you have not installed IBM Tivoli Workload Scheduler for

Applications, an error message appears. Cancel the installation and

proceed with the installation of IBM Tivoli Workload Scheduler for

Applications. See “Installing Tivoli Workload Scheduler for Applications

using the ISMP installation wizard” on page 11 for a detailed

description about how to install IBM Tivoli Workload Scheduler for

Applications.Click Next. A panel is displayed where you can choose which languages you

want to install.

8. By default, all the languages are installed. Clear the languages you do not

want to install and click Next.

9. A summary information panel is displayed. Click Next.

The installation program installs the selected languages for all the installed

access methods. The installation progress panel is displayed showing the

status of the installation.

10. When the installation has completed, a panel showing the results of the

installation is displayed. Click Finish to complete the installation.

If you receive error messages, analyze the /tmp/tws4appslangs.log and the

/tmp/TWS4APPS_installationname_LANGS^8.4.log installation log files.


silent installation

To install Tivoli Workload Scheduler for Applications, or one of the access

methods, using silent installation, you use a response file to run the installation

without user intervention. Tivoli Workload Scheduler for Applications provides

you with the TWS4APPSSilent.txt response file located on any product CD under

the RESPONSE_FILES directory. This is a template response file that you can

customize to reflect the type of installation you want to perform.

Using the silent installation method you can install one or more access methods

simultaneously. Using the ISMP silent installation you also automatically install the

Option Editor. The Option Editor is a Java-based file editor that you use to define

options for the access methods you installed.

When running the installation in silent mode no messages are displayed. Messages

are written in the /tmp/tws4apps_ismp.log and in the/tmp/TWS4APPS_installationname_accessmethod^8.4.log installation log files. To run a

silent installation, perform the following steps:

1. Create your response file or customize the TWS4APPSSilent.txt response file to

include the options required to complete the installation. See Table 5 on page 15

for a list of the available options. The response file must be accessible from the

workstation where you want to perform the installation. Entries in the response

file are in the format option=value. Each entry must be written on a separate

line.

Installing language pack using ISMP installation wizard


2. Insert the product CD for your operating system and run the setup command,

located in the INSTALLER directory:

On Windows

setup.exe -silent -options responsefile

On UNIX

setup.bin -silent -options responsefile

where:

-silent Specifies that the installation is driven by a response file.

-options responsefile

Indicates the fully qualified path to the response file that contains the

installation options. responsefile is any text file with the name and

extension you choose.

Table 5 lists the options you can specify to drive the installation.

Note: Enclose all the option values within double quotes ("), unless the value you

must specify is Boolean requiring the answer true or false.

Table 5. Options required for silent installation

Option Required Description Value

-W SETUP_TYPE_BEAN.active Yes For internal

use only.

Do not change this value. The

value is false.

-P TWS4APPS.installLocation Yes The path to

the Tivoli

Workload

Scheduler

installation

where you

want to install

Tivoli

Workload

Scheduler for

Applications.

A fully qualified path. For

example: /home/tws84/tws

-W SETUP_TYPE_BEAN.selectedSetupTypeId Yes Specifies if

you are

performing a

new

installation or

if you are

adding an

access method

to an already

existing

installation.

NEW_INSTANCE_TYPE

To perform a new

installation

UPGRADE_INSTANCE_TYPE

To add one or more access

methods to an existing

installation

-P TWS4APPS.name Yes A name for

the

installation of

Tivoli

Workload

Scheduler for

Applications.

A name. For example: tws

Installing using silent installation


Table 5. Options required for silent installation (continued)


-P R3BATCH_FEATURE.active No Specifies that

the access

method for

SAP R/3 is to

be installed.

True or False.

-W LJUSER_R3BATCH_INPUT_BEAN.LJUSER Yes

If you are

installing

the SAP

R/3

method.

The name of

the operating

system user

ID used to

launch the

SAP R/3

access

method.

The operating system user ID

user name. Usually you specify

the name of the Tivoli Workload

Scheduler user where the access

method is installed. For

example: user1

-P PSAGENT_FEATURE.active No Specifies that

the access

method

forPeopleSoft

is to be

installed.

True or False.

-W LJUSER_PSAGENT_INPUT_BEAN.LJUSER Yes

If you are

installing

the

PeopleSoft

method.

The name of

the operating

system user

ID used to

launch the

PeopleSoft

access

method.




Scheduler user where the


example: user1

-W LJUSER_PSAGENT_INPUT_BEAN.PSJOAPATH Yes

If you are

installing

the

PeopleSoft

method.

Specifies the

full path to

the psjoa.jar

file. See

“Before

installing” on

page 9 for

detailed

information.

A full path. For example:

c:\pt845\class\psjoa.jar

-P MCMAGENT_FEATURE.active No Specifies that

the access

method for

Oracle

E-Business

Suite is to be

installed.

True or False.

-W LJUSER_MCMAGENT_INPUT_BEAN.LJUSER Yes

If you are

installing

the Oracle

E-Business

Suite

method.

The name of

the operating

system user

ID used to

launch the

Oracle

E-Business

Suite access

method.



the name of the Oracle

E-Business Suite user where the

method is installed.



Table 5. Options required for silent installation (continued)


-P ZOSAGENT_FEATURE.active No Specifies that

the access

method for

z/OS is to be

installed.

True or False.

-W LJUSER_ZOSAGENT_INPUT_BEAN.LJUSER Yes

If you are

installing

the z/OS

method.

The name of

the operating

system user

ID used to

launch the

z/OS access

method.




Scheduler user where the


example: user1

The following is an example of the command you run to perform a silent

installation using the tws4appssilent_inst.txt response file on a UNIX

workstation:

setup.bin –silent –options /tmp/tws4appssilent_inst.txt

The following example shows a response file that installs the R/3 and PeopleSoft

access methods on a Windows workstation:

# INSTALL LOCATION and INSTANCE NAME

-W SETUP_TYPE_BEAN_.active=false

-P TWS4APPS.installLocation="C:\Program Files\IBM\TWS\maestro"

-P TWS4APPS.name="SILENT"

# R3BATCH SETTINGS

-P R3BATCH_FEATURE.active=true

-W LJUSER_R3BATCH_INPUT_BEAN.LJUSER="twsuser"

# PSAGENT SETTINGS

-P PSAGENT_FEATURE.active=true

-W LJUSER_PSAGENT_INPUT_BEAN.LJUSER="tws"

-W LJUSER_PSAGENT_INPUT_BEAN.PSJOAPATH="c:\pt845\class\psjoa.jar"

Installing the language pack using silent installation

To install one or all of the supported languages using silent installation you use a

response file. Using the response file you run the installation in silent mode

without user intervention. Tivoli Workload Scheduler for Applications provides

you with the TWS4APPSLangSilent.txt template response file located on any

product CD under the RESPONSE_FILES directory. This is a template response file

that you can customize to reflect which languages you want to install.

When running the installation in silent mode, no messages are displayed, but all

messages are written in the /tmp/tws4appslangs.log and in the


To run a silent installation, perform the following steps:

1. Verify that the TWS4APPS_JDKHOME environment variable is set to the

following path:


2. Create your response file, or customize the TWS4APPSLangSilent.txt template

response file, to include the languages you want to install, as described in the

TWS4APPSLangSilent.txt response file. The response file must be accessible



from the workstation where you want to perform the installation. Entries in the

response file are in the format option=value. Each entry must be written on a

separate line.

3. Insert the product CD for the operating system on which you are installing the

product and run the setup command located in the LANG_PACK directory:

On Windows

setup.exe -silent -options responsefile

On UNIX

setup.bin -silent -options responsefile

where:

-silent Specifies that the installation is driven by a response file.

-options responsefile

Indicates the fully qualified path to the response file that contains the

installation options. responsefile is any text file with the name and

extension you choose.

Table 6 lists the options you can specify to drive the installation.

Note: Enclose all the option values within double quotes (").

Table 6. Options for the language pack silent installation


-P

TWS4APPS_LANGSPACK.installLocation

Yes The path where you installed

Tivoli Workload Scheduler for

Applications.



-P TWS4APPS_LANGSPACK.name Yes A name for this installation of

the Tivoli Workload Scheduler

for Applications language pack.

A name. For example: TWS

-P LANGSPACK_DE_FEATURE.active No Specifies that the German

language is installed.

true or false. The default

value is true.

-P LANGSPACK_ES_FEATURE.active No Specifies that the Spanish



value is true.

-P LANGSPACK_IT_FEATURE.active No Specifies that the Italian



value is true.

-P LANGSPACK_FR_FEATURE.active No Specifies that the French



value is true.

-P LANGSPACK_JA_FEATURE.active No Specifies that the Japanese



value is true.

-P LANGSPACK_KO_FEATURE.active No Specifies that the Korean



value is true.

-P LANGSPACK_PT_BR_FEATURE.active No Specifies that the Brazilian

Portuguese language is

installed.


value is true.

-P

LANGSPACK_ZH_CN_FEATURE.active

No Specifies that the Chinese

Simplified language is installed.


value is true.

-P

LANGSPACK_ZH_TW_FEATURE.active

No Specifies that the Chinese

Traditional language is

installed.


value is true.

Installing language pack using silent installation


The following is an example of the command you run to perform a silent

installation using the tws4appslangsilent.txt response file on a UNIX

workstation:

setup.bin –silent –options /tmp/tws4appslangsilent.txt

The following is an example of a response file that installs the Italian and French

languages.

# INSTALL LOCATION and INSTANCE NAME

-P TWS4APPS_LANGSPACK.installLocation="/home/tws84/tws"

-P TWS4APPS_LANGSPACK.name="SILENT"

# INSTALL THE ITALIAN AND FRENCH LANGUAGE PACKS

# -P LANGSPACK_IT_FEATURE.active="false"

# -P LANGSPACK_FR_FEATURE.active="false"

-P LANGSPACK_ZH_TW_FEATURE.active="false"

-P LANGSPACK_ZH_CN_FEATURE.active="false"

-P LANGSPACK_ES_FEATURE.active="false"

-P LANGSPACK_DE_FEATURE.active="false"

-P LANGSPACK_JA_FEATURE.active="false"

-P LANGSPACK_KO_FEATURE.active="false"

-P LANGSPACK_PT_BR_FEATURE.active="false"

Installing IBM Tivoli Workload Scheduler for Applications

using Tivoli Software Distribution, version 4.1 or Tivoli

Configuration Manager, version 4.2 or later

This section describes how to install IBM Tivoli Workload Scheduler for

Applications and its language pack by using a software package block (SPB).

You can install any access method by distributing a software package block using

the Tivoli Desktop or the winstsp command of Tivoli Software Distribution,

version 4.1 or the Software Distribution component of IBM Tivoli Configuration

Manager, version 4.2 or later. The distribution and installation of the software

package blocks can be performed on workstations running IBM Tivoli Management

Framework.

The software package blocks are located on the IBM Tivoli Workload Scheduler for

Applications, version 8.4 CDs. Table 7 lists the software package blocks available to

install IBM Tivoli Workload Scheduler for Applications and their location in the

product CDs.

The software package blocks to install the language packs are located on the CD

related to the operating system for which you want to perform the installation.

Table 8 on page 22 lists the software package block available to install language

packs and its location on the product CDs. See “For language pack” on page 25 for

a detailed explanation about how to install the language packs using Tivoli

Software Distribution, version 4.1 or the Software Distribution component of IBM

Tivoli Configuration Manager, version 4.2 or later.

Table 7. List of software package blocks to install IBM Tivoli Workload Scheduler for Applications

.SPB File Software Package Description CD Location

TWS4APPS_MCMAGENT_AIX.SPB Installs the AIX Oracle E-Business

Suite extended agent.

productCD for operating

system/AIX/INSTALLER/SPB

TWS4APPS_MCMAGENT_HP.SPB Installs the HP-UX for PA-RISC

Oracle E-Business Suite extended

agent.


system/HP/INSTALLER/SPB

Installing language pack using silent installation


Table 7. List of software package blocks to install IBM Tivoli Workload Scheduler for Applications (continued)


TWS4APPS_MCMAGENT_HPIA64.SPB Installs the HP-UX IA64 for

Integrity Oracle E-Business Suite

extended agent.


system/HPIA64/INSTALLER/SPB

TWS4APPS_MCMAGENT_SOLARIS.SPB Installs the Solaris Oracle

E-Business Suite extended agent.


system/SOLARIS/INSTALLER/SPB

TWS4APPS_MCMAGENT_LINUX.SPB

1 Installs the Linux Oracle

E-Business Suite extended agent.


system/LINUX/INSTALLER/SPB

TWS4APPS_PSAGENT_I386NT.SPB Installs the Windows PeopleSoft

extended agent.


system/I386NT/INSTALLER/SPB

TWS4APPS_PSAGENT_LINUX.SPB

1 Installs the Linux PeopleSoft

extended agent



TWS4APPS_PSAGENT_HP.SPB Installs the HP-UX for PA-RISC

PeopleSoft extended agent



TWS4APPS_PSAGENT_HPIA64.SPB Installs the HP-UX IA64 for

IntegrityPeopleSoft extended agent



TWS4APPS_R3BATCH_AIX.SPB Installs the AIX R/3 extended

agent.



TWS4APPS_R3BATCH_AIX64.SPB Installs the AIX for 64 bit R/3

extended agent



TWS4APPS_R3BATCH_HP.SPB Installs the HP-UX for PA-RISC 32

bit R/3 extended agent.



TWS4APPS_R3BATCH_HP64.SPB Installs the HP-UX for PA-RISC 64

bit R/3 extended agent.



TWS4APPS_R3BATCH_HPIA64.SPB Installs the HP-UX IA64 for

Integrity R/3 extended agent.



TWS4APPS_R3BATCH_I386NT.SPB Installs the Windows R/3

extended agent.



TWS4APPS_R3BATCH_LINUX390.SPB

1 Installs the Linux for zSeries R/3

extended agent.


system/LINUXS390/INSTALLER/SPB

TWS4APPS_R3BATCH_LINUX.SPB Installs the Linux R/3 extended

agent



TWS4APPS_R3BATCH_SOLARIS.SPB Installs the Solaris R/3 extended

agent.



TWS4APPS_R3BATCH_SOLARIS64.SPB Installs the Solaris for 64 bit R/3

extended agent.



TWS4APPS_ZOSAGENT_AIX.SPB Installs the AIX z/OS extended

agent.



TWS4APPS_ZOSAGENT_HP.SPB Installs the HP-UX for PA-RISC

z/OS extended agent.



TWS4APPS_ZOSAGENT_HPIA64.SPB Installs the HP-UX IA64 for

Integrity z/OS extended agent.



TWS4APPS_ZOSAGENT_I386NT.SPB Installs the Windows z/OS

extended agent.



TWS4APPS_ZOSAGENT_LINUX.SPB Installs the Linux z/OS extended

agent.



TWS4APPS_ZOSAGENT_LINUX390.SPB1 Installs the Linux for zSeries z/OS

extended agent.



Installing using Tivoli Software Distribution or Tivoli Configuration Manager


|||||

|||||

|||||

|||||

|||||

|||||

Table 7. List of software package blocks to install IBM Tivoli Workload Scheduler for Applications (continued)


TWS4APPS_ZOSAGENT_SOLARIS.SPB Installs the Solaris z/OS extended

agent.



TWS4APPS_OPTED.SPB2 Installs the Option Editor. productCD for operating

system/operating

system/INSTALLER/SPB

JRE142_AIX.SPB Installs the AIX Java Runtime

Environment (JRE) version 1.4.2.


system/AIX/JVM_CM

JRE142_HP.SPB Installs the HP-UX for PA-RISC

Java Runtime Environment (JRE)

version 1.4.2.


system/HP/JVM_CM

JRE142_HPIA64.SPB Installs the HP-UX for Integrity

Java Runtime Environment (JRE)

version 1.4.2.


system/HPIA64/JVM_CM

JRE142_I386.SPB Installs the Windows Java

Runtime Environment (JRE)

version 1.4.2.


systemI386NT/JVM_CM

JRE142_LINUX.SPB1 Installs the Linux for xSeries Java


version 1.4.2.


system/LINUX/JVM_CM

JRE142_ZLINUX.SPB1 Installs the Linux for zSeries Java


version 1.4.2.


system/ZLINUX/JVM_CM

JRE142_SOLARIS.SPB Installs the Solaris Java Runtime

Environment (JRE) version 1.4.2.


system/SOLARIS/JVM_CM

TWS4APPS_COMMON_AIX.SPB Installs GSKit, License

Information, and License

Agreement files for AIX



TWS4APPS_COMMON_HP.SPB Installs GSKit, License


Agreement files for HP



TWS4APPS_COMMON_HP.SPB Installs GSKit, License


Agreement files for HP IA64



TWS4APPS_COMMON_I386NT.SPB Installs GSKit, License


Agreement files for Windows



TWS4APPS_COMMON_LINUX.SPB Installs GSKit, License


Agreement files for Linux



TWS4APPS_COMMON_LINUX390.SPB Installs GSKit, License


Agreement files for Linux for

zSeries



TWS4APPS_COMMON_SOLARIS.SPB Installs GSKit, License


Agreement files for Solaris



Notes:

1. The SPB packages for Linux cannot be imported using Tivoli Software

Distribution, version 4.1.



|||||

||||

||

||||

||

||||

||

||||

||

||||

||

|||||

||

||||

||

2. If you already have the Java Runtime Environment (JRE) installed, to use the

Option Editor you still need to install Java Runtime Environment (JRE), version

1.4.2.

Table 8. Software package block to install IBM Tivoli Workload Scheduler for Applications language pack

Language Pack .SPB

File Software Package Description CD Location

TWS4APPS_LANGS.SPB Installs the language pack for all

the extended agents.

productCD for operating system/operating

system/LANG_PACK

Using this method you can install only one access method per software package

block. If you use multiple SPBs to install additional access methods, be careful to

use different names for the software package profile. The software package profile

name has the following format:

v For the Oracle E-Business Suite access method:

TWS4APPS_installationname_MCMAGENT_operatingsystem.8.4

v For the PeopleSoft access method:

TWS4APPS_installationname_PSAGENT_operatingsystem.8.4

v For the R/3 access method:

TWS4APPS_installationname_R3BATCH_operatingsystem.8.4

v For the z/OS access method:

TWS4APPS_installationname_ZOS_operatingsystem.8.4

v For the Option Editor:

TWS4APPS_installationname_OPTED.8.4

where:

installationname

Specifies the name that you used for the IBM Tivoli Workload Scheduler for

Applications installation. For example, TWS.

operating system

Specifies the operating system where you are installing the software package.

If you choose to drive the installation process from the Tivoli Desktop, and your

Tivoli Workload Scheduler engine on the target workstation is version 8.2 or later,

make sure you know the name of the installation directory of the engine before

you start.

Table 9 describes the options required to install Tivoli Workload Scheduler for

Applications using SPBs.

Table 9. Options to install Tivoli Workload Scheduler for Applications using SPBs

Option Required Description

INSTALL_DIR Yes The fully qualified path to the Tivoli Workload

Scheduler installation where you want to install Tivoli

Workload Scheduler for Applications.

LJUSER Yes The name of the operating system user ID used to

launch the access method.

PSJOAPATH Yes, if you are

installing the

PeopleSoft

method.

The full path to the psjoa.jar file. For detailed

information, see “Before installing” on page 9.



Table 10 describes the options to install the language pack using SPBs.

Table 10. Options to install the language packs using SPBs


INSTALL_DIR Yes The path to the Tivoli Workload

Scheduler installation where you want

to install Tivoli Workload Scheduler for

Applications.

Fully qualified

path.

INST_OPTED No Option Editor languages. true or false. The

default value is

false.

DE No German language pack. true or false. The

default value is

true.

ES No Spanish language pack. true or false. The

default value is

true.

FR No French language pack. true or false. The

default value is

true.

IT No Italian language pack. true or false. The

default value is

true.

JA No Japanese language pack. true or false. The

default value is

true.

KO No Korean language pack. true or false. The

default value is

true.

PT_BR No Brazilian Portuguese language pack. true or false. The

default value is

true.

ZH_CN No Chinese Simplified language pack. true or false. The

default value is

true.

ZH_TW No Chinese Traditional language pack. true or false. The

default value is

true.

Installation procedure

To install a software package, perform the following actions, using either the

command line or the Tivoli Desktop.

1. Create a software package profile

2. Import the software package block into a software package profile. Do this for

the software package blocks for the:

v Access methods you want to install

v Language pack

If you want to use the Option Editor:

v Java Runtime Environment (JRE) version 1.4.2

v Option Editor



Note: Before using the Option Editor ensure you have already installed the

access method and the JRE software package blocks.3. Install the software package profile on the endpoints managed by IBM Tivoli

Management Framework.

Refer to the IBM Tivoli Configuration Manager documentation for a detailed

explanation about how to perform the above steps.

For the Java Runtime Environment (JRE): To install the JRE142_AIX.SPB software

package block on an AIX workstation for the TWSuser user, perform the steps

below. A different Java Runtime Environment (JRE) software package block exists

for each operating system.

1. Import the JRE142_AIX.SPB software package block file in a Tivoli Management

Framework profile manager, for example the jreprofile profile manager, by

using the following command:

wimpspo -c jreprofile -f src_path/JRE142_AIX.SPB -t build

-p dest_path_local/JRE142_AIX.SPB TWS4APPS_TWSuser_JRE142_AIX.8.4

2. Install the TWS4APPS_TWSuser_JRE142AIX.8.4 software package profile on a

workstation which must also be defined as a Tivoli Management Framework

endpoint. For example, to install the TWS4APPS_TWSuser_JRE142_AIX.8.4

software package profile on a workstation whose hostname is epAIX, use the

following command:

winstsp -D INSTALL_DIR=twshome TWS4APPS_TWSuser_JRE142_AIX.8.4 @epAIX

When the installation log, in this example the $BINDIR/../swdis/work/TWS4APPS_TWSuser_JRE142_AIX.8.4.log file, shows an Operation Successful

message, the installation process is complete.

For SAP R/3: To install the SAP R/3 access method using the

TWS4APPS_R3BATCH_AIX.SPB software package block for the TWSuser user, perform

the following steps:

1. Import the TWS4APPS_R3BATCH_AIX.SPB software package block into a Tivoli

Management Framework profile manager, for example, the r3profile profile

manager, by using the following command:

wimpspo -c r3profile -f src_path/TWS4APPS_R3BATCH_AIX.SPB -t build

-p dest_path_local/TWS4APPS_R3BATCH_AIX.SPB TWS4APPS_TWSuser_R3BATCH_AIX.8.4

TWS4APPS_TWS_R3BATCH_AIX.8.4 must refer to dest_path_local/TWS44APPS_R3BATCH_AIX.SPB as the local file holding the required information.

Note: For multiple installations of the same software package block on the

same workstation, you must rename the software package profile for

each installation.

2. Install the TWS4APPS_TWSuser_R3BATCH_AIX.8.4 software package profile on a


endpoint. For example, to install the TWS4APPS_TWS_R3BATCH_AIX.8.4 software

package profile on a workstation whose hostname is epwaix, use the following

command:

winstsp -D INSTALL_DIR=twshome -D LJUSER=TWSuser

TWS4APPS_TWSuser_R3BATCH_AIX.8.4 @epwaix

When the installation log, in this example the $BINDIR/../swdis/work/TWS4APPS_TWSuser_R3BATCH_AIX.8.4.log file, shows an Operation Successful

message, the installation process is complete.



For PeopleSoft: To install the PeopleSoft access method using the

TTWS4APPS_PSAGENT_I386NT.SPB software package block for the TWSuser user,

perform the following steps:

1. Install the Java Runtime Environment as described in the installation procedure

“For the Java Runtime Environment (JRE)” on page 24.

2. Import the TWS4APPS_PSAGENT_I386NT.SPB software package block file into a

Tivoli Management Framework profile manager, for example the

psagentprofile profile manager, by using the following command:

wimpspo -c psagentprofile -f src_path/TWS4APPS_PSAGENT_I386NT.SPB -t build

-p dest_path_local/TWS4APPS_PSAGENT_I386NT.SPB TWS4APPS_TWSuser_PSAGENT.8.4

TWS4APPS_TWS_PSAGENT.8.4 must refer to dest_path_local/TWS4APPS_PSAGENT_I386NT.SPB as the local file holding the required information.


same workstation, you must rename the software package profile for

each installation.

3. Install the TWS4APPS_TWS_PSAGENT.8.4 software package profile on a workstation

which must also be defined as a Tivoli Management Framework endpoint. For

example, to install the TWS4APPS_TWSuser_PSAGENT.8.4 software package profile

on a workstation whose hostname is epwwindows, use the following command:

winstsp -D INSTALL_DIR=twshome -D LJUSER=TWSuser

-D PSJOAPATH=c:\pt845\class\psjoa.jar TWS4APPS_TWSuser_PSAGENT.8.4 @epwwindows

When the installation log, in this example the $BINDIR/../swdis/work/TWS4APPS_TWS_PSAGENT.8.4.log file, shows an Operation Successful message, the

installation process is complete.

For the Option Editor: The software package block of the Option Editor is the

same for all the operating systems. To install the TWS4APPS_OPTED.SPB software

package block on an AIX workstation for the TWSuser user, perform the following

steps:

1. Import the TWS4APPS_OPTED.SPB software package block file into a Tivoli

Management Framework profile manager, for example the optprofile profile

manager, by using the following command:

wimpspo -c optprofile -f src_path/TWS4APPS_OPTED.SPB -t build

-p dest_path_local/TWS4APPS_OPTED.SPB TWS4APPS_TWSuser_OPTED.8.4

2. Install the TWS4APPS_TWSuser_OPTED.8.4 software package profile on a


endpoint. For example, to install the TWS4APPS_TWSuser_OPTED.8.4 software

package profile on a workstation whose hostname is epAIX, use the following

command:

winstsp -D INSTALL_DIR=twshome TWS4APPS_TWSuser_OPTED.8.4 @epAIX

When the installation log, in this example the $BINDIR/../swdis/work/TWS4APPS_TWSuser_OPTED.8.4.log file, shows an Operation Successful message,

the installation process is complete.

For language pack: This section describes how to install the TWS4APPS_LANGS.SPB

software package block. To install the language pack for any access method using

TWS4APPS_LANGS.SPB for the twsuser, perform the following steps:

1. Import the TWS4APPS_LANGS.SPB software package block into a Tivoli

Management Framework profile manager, for example the langpackprofile

profile manager, by using the following command:



wimpspo -c langpackprofile -f src_path/TWS4APPS_LANGS.SPB -t build

-p dest_path_local/TWS4APPS_LANGS.SPB TWS4APPS_TWSuser_LANGS.8.4

TWS4APPS_TWSuser_LANGS.8.4 must refer to dest_path_local/TWS4APPS_LANGS.SPB as the local file holding the required information.


same workstation, you must rename the software package block for each

installation.

2. Install the TWS4APPS_TWSuser_LANGS.8.4 software package profile on a


endpoint. For example, to install the TWS4APPS_TWS_LANGS.8.4 software package

profile on a workstation whose hostname is epwaix, use the following

command:

winstsp -D INSTALL_DIR=twshome -D TWS4APPS_TWSuser_LANGS.8.4

@epwaix

Using this command you install all the languages simultaneously.

When the installation log, in this example the $BINDIR/../swdis/work/TWS4APPS_TWSuser_LANGS.8.4.log file, shows an Operation Successful message,

the installation process is complete.

Installing IBM Tivoli Workload Scheduler for Applications

using twsappsinst

This section explains how to perform the following tasks using the twsappsinst

script:

v Install IBM Tivoli Workload Scheduler for Applications.

v Add an access method to an already existing installation of Tivoli Workload


Note: This method does not install the Option Editor. It installs the Java Runtime

Environment for PeopleSoft only.

To install IBM Tivoli Workload Scheduler for Applications using twsappsinst,



product, or copy locally the ALT_INST directory and its content.

2. Log in as root and locate the installation directory of the operating system

where you want to install.

3. Run the twsappsinst script using the syntax described below. The software is

installed by default in the home directory of the user, referred to as twshome. If

you receive error messages, analyze the /tmp/twappsint.log and the


To know the syntax for the twsappsinst command, run twsappsinst as follows:

�� twsappsinst -u ��

If you want to know the version of the twsappsinst command, run twsappsinst as

follows:



�� twsappsinst -v ��

The syntax of the twsappsinst command to install IBM Tivoli Workload Scheduler

for Applications or add an access method is as follows:

��

twsappsinst

-install

-twsuser

TWSUser

�

Access

method

�

� -inst_dir TWS_installation_path

-lang

messages_language ��

Access method:

(1)

-mcm_ljuser

ljuser_name

-r3_ljuser

ljuser_name

-ps_ljuser

ljuser_name

-psjoapath

psjoa_path

-zos_ljuser

ljuser_name

Notes:

1 Do not specify the same access method more than once.

Table 11 describes the twsappsinst parameters used to install IBM Tivoli Workload


Table 11. twsappsinst parameters to install IBM Tivoli Workload Scheduler for Applications

Parameter Required Description

-install Yes Installs Tivoli Workload Scheduler for Applications.

-wsuser TWSUser Yes The name of the user for which Tivoli Workload Scheduler is

installed. For example: tws84. The software is installed in this user's

home directory. This user name is not to be confused with the user

performing the installation logged on as root. Tivoli Workload

Scheduler for Applications is installed under the home directory of

the specified user. Enclose the name within double quotes if it

contains a blank.

-r3_ljuser ljuser Yes

If you are installing the

SAP R/3 access

method.

Installs the SAP R/3 access method. ljuser is the name of the

operating system user ID used to launch the access method.

-ps_ljuser ljuser

-psjopath psjopath

Yes


PeopleSoft access

method.

Installs the PeopleSoft access method. ljuser is the name of the

operating system user ID used to launch the access method.

psjoapath is the full path to the psjoa.jar file. See “Before installing”

on page 9 for detailed information.

-mcm_ljuser ljuser Yes


Oracle E-Business Suite

access method.

Installs the Oracle E-Business Suite access method. ljuser is the name

of the operating system user ID used to launch the access method.

Installing using twsappsinst


Table 11. twsappsinst parameters to install IBM Tivoli Workload Scheduler for Applications (continued)


-zos_ljuser ljuser Yes


z/OS access method.

Installs the z/OS access method. ljuser is the name of the operating

system user ID used to launch the access method.

-inst_dir

TWS_installation_

path

No The path to the Tivoli Workload Scheduler installation where you

want to install Tivoli Workload Scheduler for Applications. The

software is installed by default in the home directory of the user,

referred to as twshome. For example: /home/tws84/tws.

-lang

messages_language

No The language in which the twsappsinst messages are displayed. If

not specified, the system LANG is used. If the related catalog is

missing, the default C language catalog is used. Possible values are:

de German

it Italian

es Spanish

fr French

es Spanish

ko Korean

ja Japanese

pt_BR Brazilian Portuguese

zh_CN Chinese Simplified

zh_TW Chinese Traditional

Examples of how to install Tivoli Workload Scheduler for

Applications using twsappsinst

This section shows some examples to install IBM Tivoli Workload Scheduler for

Applications access methods using twsappsinst.

The following is an example of how to install the Tivoli Workload Scheduler for

Applications R/3 access method using twsappsinst:

twsappsinst -install -twsuser tws84 -r3_ljuser r3user -inst_dir

/home/tws84/tws -lang it

The following is an example of how to install the Tivoli Workload Scheduler for

Applications for PeopleSoft and Tivoli Workload Scheduler for Applications for

z/OS using twsappsinst:

twsappsinst -install -twsuser tws84

-ps_ljuser psuser -psjoapath c:\pt845\class\psjoa.jar

-zos_ljuser zosuser -inst_dir /home/tws84/tws -lang it

Installing the language pack using twsappsinst

This section explains how to perform the following tasks using twsappsinst script:

v Install the IBM Tivoli Workload Scheduler for Applications language pack

v Add a language to an existing IBM Tivoli Workload Scheduler for Applications

language pack.

To install the IBM Tivoli Workload Scheduler for Applications language pack using

twsappsinst, perform the following steps:

1. Ensure you have already installed IBM Tivoli Workload Scheduler for

Applications version 8.4.

2. Insert the product CD appropriate for the operating system on which you are

installing the product, or copy locally the altinst directory and its content.

Installing using twsappsinst




4. Run the twsappsinst script using the syntax described on page 29. The

software is installed by default in the user's home directory, referred to as

twshome. If you receive error messages, analyze the /tmp/twappsint.log and

the /tmp/TWS4APPS_installationname_LANGS^8.3.log installation log file.



To know the version of the twsappsinst command, run twsappsinst as follows:


The syntax of the twsappsinst command to install IBM Tivoli Workload Scheduler

for Applications language pack or add a language is as follows:

��

twsappsinst

-languages

-twsuser

TWSUser

�

Language

pack

�

� -inst_dir

TWS_installation_path

-lang


Language pack:

(1)

-de

-it

-es

-fr

-ko

-ja

-pt_BR

-zh_CN

-zh_TW

Notes:

1 Do not specify the same language pack more than once.

Table 12 describes the twsappsinst parameters used to install IBM Tivoli Workload

Scheduler for Applications language pack:


language pack


-languages Yes Installs IBM Tivoli Workload Scheduler for Applications

language pack or one of the supported languages.

Installing language pack using twsappsinst



language pack (continued)


-twsuser TWSuser Yes The name of the user for which IBM Tivoli Workload

Scheduler is installed. For example: tws. The software is

installed in this user's home directory. This user name is not

to be confused with the user performing the installation

logged on as root. Tivoli Workload Scheduler will be

installed under the HOME directory of the specified user.

Enclose the name within double quotes if it contains a blank.

-Language pack Yes The language you want to install. Possible values are:

de German

it Italian

es Spanish

fr French

ko Korean

ja Japanese




-inst_dir

TWS_install_path

No The path to the Tivoli Workload Scheduler installation where

you want to install Tivoli Workload Scheduler for

Applications. The software is installed by default in the

user's home directory, referred to as twshome. For example:

/home/tws84/tws.

-lang

messages_language

No The language in which the twsappsinst messages are

displayed. If not specified, the system LANG is used. If the

related catalog is missing, the default C language catalog is

used. Possible values are:

de German

it Italian

es Spanish

fr French

ko Korean

ja Japanese




Example of how to install the Tivoli Workload Scheduler for

Applications language pack using twsappsinst

This section shows an example to install the Tivoli Workload Scheduler for

Applications language pack using twsappsinst:

twsappsinst -languages -twsuser tws84 -it -de -inst_dir /home/tws84/tws -lang it

Installing language pack using twsappsinst


Completing the installation of the access method for Oracle

E-Business Suite

After you have installed Tivoli Workload Scheduler for Applications, perform the

following steps to complete the installation of the access method for Oracle

E-Business Suite:

1. Ensure that the Oracle Applications logon has permissions to write in the

methods, and OracleTMP directories located in TWShome.

2. Log on as an Oracle Applications UNIX user, who has access to all the files in

the Oracle Application Top directory.

3. In the TWShome/methods/mcmsetting.sh file, replace the variable

ORACLE_SID_database_name with the actual name of the Oracle SID database.

4. In the Oracle Application Top directory, usually the $APPL_TOP installation

directory, copy the content of the following files:

v APPScontextname.env files into the APPScontextname_MCM.env file.

v contextname.env files into the contextname_MCM.env file.

where contextname is the Applications context name. The default value is the

SID_hostname.

5. Modify the APPScontextname_MCM.env file by replacing the line:

. /APPL_installation_path/contextname.env

with:

. /APPL_installation_path/contextname_MCM.env

where APPL_installation_path is the complete installation path.

6. Modify the Oracle E-Business Suite contextname_MCM.env file as follows:

a. At the end of the file, add the line:

.TWShome+/methods/mcmsetting.sh

b. Set the APPLFENV environment variable to the contextname_MCM.env file.

c. If you are working with a version of Oracle E-Business Suite prior to 11.0,

append MCM to the APPLSHAR and APPLFULL variables as follows:

APPLSHAR=’ALR FF MCM’

APPLFULL=’FND AD AX AK GL RG INV OP MCM’

7. Run the APPScontextname_MCM.env main application environment file to set the

environment:

. APPScontextname_MCM.env

8. Make a backup copy of the TWShome/methods/OracleTMP directory.

9. Change to the installed directory:

cd TWShome/methods/OracleTMP

10. Change the user and group ownership of the installed files to that of your

Oracle E-Business Suite application owner.

11. To link the binary files, from the TWShome/methods/OracleTMP directory, run the

installation script mcminstall with the following command:

sh mcminstall

Note: If you need to define the TWO_TASK environment variable to allow for an

Oracle three-tier configuration, do not set it externally from mcminstall

or in any scripts provided as input parameters. If you do, this prevents

you from performing the link steps successfully.

Completing installation of Oracle E-Business Suite access method


||

|

|

|

|

||

||

The installation process now attempts to link the Tivoli Workload

Scheduler for Applications executables with the Oracle E-Business Suite

application shared libraries.

After the link process has completed successfully, you find the

following executables in the $MCM_TOP/bin directory:

v MCMLJ

v MCMSTAT

v MCMTJ

These binary files are created by the adrelink utility for Oracle

E-Business Suite. This utility also registers the MCM as a module in

Oracle E-Business Suite.

An Oracle Tivoli shell panel is displayed.

12. Perform the following steps:

a. Press i to install.

b. Press c to continue the installation.

c. Enter the name of the installation log file. The default is mcminstall.log,

located in the TWShome/methods directory.

d. Enter the name of the APPScontextname_MCM.env main application

environment file. The default is APPLSYS.env.

e. Enter the TWShome installation directory.13. Edit the options file. For details, see Chapter 7, “Configuring the Oracle

E-Business Suite access method,” on page 63 and Chapter 3, “Setting options

with the Option Editor,” on page 43.

The installation is now complete. If you encounter problems during the link step,

fix them and run the link step again, because this step is responsible for creating

the binary files that enable Tivoli Workload Scheduler for Applications to interact

with the Oracle Concurrent Manager in submitting and monitoring jobs.

Completing installation of Oracle E-Business Suite access method


Upgrading

To upgrade Tivoli Workload Scheduler for Applications version 8.2, 8.2.1, or 8.3 to

version 8.4, use one of the following methods:

v The InstallShield MultiPlatform (ISMP) wizard

v The silent installation

v Tivoli Software Distribution, version 4.1 or the Software Distribution component

of Tivoli Configuration Manager, version 4.2 or later.

v In a UNIX environment, the twsappsinst command.

Upgrading Tivoli Workload Scheduler for Applications using

the ISMP installation wizard

To upgrade Tivoli Workload Scheduler for Applications version 8.2, 8.2.1, or 8.3 to

version 8.4 using the ISMP installation wizard, perform the following steps:

1. From the product CD, or from an image, run the setup installation command

for the operating system on which you are installing the product. The setup

installation commands are located in operating system specific directories

located in the INSTALLER directory. The installation starts.

Note: If you decide to perform the installation from an image ensure that the

path where you copy the images does not contains blanks and to

maintain the CD directory structure






to accept the license agreement. Click Next. The Select the Type of Installation

panel is displayed.

5. Select Upgrade. The installation program detects and lists all the installations

of Tivoli Workload Scheduler for Applications version 8.2, 8.2.1, or 8.3 on your

workstation.

6. Select the installation that you want to upgrade. If the program does not

detect any existing installation, click Cancel and proceed with a new

installation as described in “Installing” on page 10.

7. Click Next. A summary information window is displayed.

8. Click Next. The installation process begins the upgrade process. The

installation progress window is displayed showing the status of the upgrade.

9. When the upgrade has completed, a window is displayed asking if you want

to open the Option Editor.

The Option Editor is a Java-based file editor that you use to define options for

the access methods you installed. If you decide not to run the Option Editor

now, you can do it later. If you click Yes, the Option Editor is displayed and

you can set your options for the methods you installed. See Chapter 3,

“Setting options with the Option Editor,” on page 43 to learn how to use the

Option Editor.

If you click No, or when you have finished with the Option Editor, the

installation exit window is displayed.

10. Click Finish to exit the installation wizard and complete the upgrade.

Upgrading


Note: If you want to install the language pack after this installation, you need

to log out and log in from the UNIX shell before installing the language

pack.

If you received error messages, analyze the /tmp/tws4pps_ismp.log and the


Note: On UNIX operating systems, if you want to install the language pack after

the upgrade, you need to log out and log in from the UNIX shell before

installing the language pack.


the silent installation

To upgrade Tivoli Workload Scheduler for Applications using the silent installation,

you must follow the same procedure outlined in “Installing Tivoli Workload

Scheduler for Applications using the silent installation” on page 14. Table 13 shows

the option required for a silent upgrade.

Table 13. Options required for silent upgrade


-W SETUP_TYPE_BEAN.active Yes For internal use

only.

Do not change this value. The

value is false.

-P TWS4APPS.installLocation Yes The path to the

Tivoli Workload

Scheduler

installation where

you want to install

Tivoli Workload

Scheduler for

Applications.



-W SETUP_TYPE_BEAN.selectedSetupTypeId Yes Specifies that you

are upgrading from

version 8.2, 8.2.1, or

8.3 to version 8.4.

MIGRATE_INSTANCE_TYPE

-P TWS4APPS.name Yes A name for the

installation of Tivoli

Workload Scheduler

for Applications.

A name. For example: tws


Tivoli Configuration Manager

To upgrade Tivoli Workload Scheduler for Applications using Tivoli Configuration

Manager, you must follow the same procedure outlined in “Installing IBM Tivoli

Workload Scheduler for Applications using Tivoli Software Distribution, version 4.1

or Tivoli Configuration Manager, version 4.2 or later” on page 19.

To see a list of the packages installed on the workstation by Software Distribution,

use either of the two following procedures:

v Use the Inventory component of Tivoli Configuration Manager version 4.2.1 or

later, to run the query named CM_STATUS_QUERY and list which software packages

are installed on which workstation. Refer to the IBM Tivoli Configuration Manager

User’s Guide for Inventory, version 4.2.1 or later for specific information.

v View the Software Distribution log files on the workstation. Every Software

Distribution package has its own log file. A log file is a text file that records the

Upgrading using ISMP installation wizard


installation and uninstallation history of the package. For example, the log file

on an AIX system of the SAP R/3 access method package, r3batch_tws_AIX.log,

is stored in the $BINDIR/../swdis/work directory. To initialize the $BINDIR

environment path of Tivoli Management Framework, launch the following

command:

. /etc/Tivoli/setup_env.sh


twsappsinst

To upgrade IBM Tivoli Workload Scheduler for Applications version 8.2, 8.2.1, or

8.3 to version 8.4 using twsappsinst, perform the following steps:

1. Ensure you have already installed IBM Tivoli Workload Scheduler for

Applications version 8.2, 8.2.1, or 8.3.


product, or copy locally the altinst directory and its content.



4. Run the twsappsinst script using the syntax described below. If you receive

error messages, analyze the twsappsinst.log file. and the /tmp/TWS4APPS_installationname_accessmethod^8.4.log installation log files.



To know the version of the twsappsinst command, run twsappsinst as follows:


The syntax of the twsappsinst command to upgrade IBM Tivoli Workload

Scheduler for Applications is as follows:

�� twsappsinst -upgrade -twsuser TWSUser �

� -inst_dir


-lang


Table 14 describes the twsappsinst parameters used to upgrade IBM Tivoli

Workload Scheduler for Applications:

Table 14. twsappsinst parameters to upgrade IBM Tivoli Workload Scheduler for

Applications


-upgrade Yes Upgrades IBM Tivoli Workload Scheduler for Applications

version 8.2, 8.2.1, or 8.3 to version 8.4.

-twsuser

TWSUser

Yes The name of the user for which Tivoli Workload Scheduler is

upgraded. For example: tws84. The software is upgraded in

this user's home directory. Enclose the name within double

quotes if it contains a blank.

Upgrading using Tivoli Configuration Manager


Table 14. twsappsinst parameters to upgrade IBM Tivoli Workload Scheduler for

Applications (continued)


-inst_dir

TWS_install_path

No The path to the Tivoli Workload Scheduler installation where

you want to upgrade Tivoli Workload Scheduler for

Applications. The software is installed by default in the

user's home directory, referred to as twshome. For example:

/home/tws84/tws.

-lang

messages_language

No The language in which the twsappsinst messages related to

the upgrade process are displayed. If not specified, the

system LANG is used. If the related catalog is missing, the

default C language catalog is used. Possible values are:

de German

it Italian

es Spanish

fr French

ko Korean

ja Japanese




Example of how to upgrade Tivoli Workload Scheduler for

Applications to version 8.4 using twsappsinst

This section shows an example to upgrade Tivoli Workload Scheduler for

Applications version 8.2, 8.2.1, or 8.3 to version 8.4 using twsappsinst:

twsappsinst -upgrade -twsuser tws84 -inst_dir /home/tws84/tws –lang it

Uninstalling

When you uninstall Tivoli Workload Scheduler for Applications, you can choose to

uninstall:

v The access methods (this includes the Option Editor):


For this access method, regardless of the uninstallation procedure you choose,

you must complete the uninstallation as described in “Completing the

removal of the access method for Oracle E-Business Suite” on page 41.

– PeopleSoft

– SAP R/3

– z/OSv One or more Tivoli Workload Scheduler for Applications language packs.

To uninstall Tivoli Workload Scheduler for Applications from a workstation, follow

the same procedure you used at installation time:

v If you installed using ISMP, uninstall using an ISMP-compatible method.

v If you installed using software distribution, uninstall using the same method.

v If you installed using twsappsinst, uninstall using the same method.

However, if you installed Tivoli Workload Scheduler for Applications using ISMP,

but you want to perform a centralized uninstallation of the Tivoli Workload

Scheduler for Applications, use the procedure described in Chapter 30,

“Troubleshooting,” on page 251.

Upgrading using twsappsinst


||

||

||||||

|

Note: If you installed the language pack using ISMP, you must uninstall it before

uninstalling Tivoli Workload Scheduler for Applications.

To uninstall Tivoli Workload Scheduler for Applications and its language packs,

you can use any of the following procedures:

ISMP wizard

For details, see “Uninstalling Tivoli Workload Scheduler for Applications using

ISMP wizard” on page 38 and “Uninstalling the language pack using ISMP

wizard” on page 38.

Tivoli Software Distribution, version 4.1 or the Software Distribution component

of Tivoli Configuration Manager, version 4.1 or later

For details, see “Uninstalling Tivoli Workload Scheduler for Applications or its

language pack using Tivoli Configuration Manager” on page 39.

Silent uninstallation

For details, see “Uninstalling the language pack using silent uninstallation” on

page 39 and “Uninstalling Tivoli Workload Scheduler for Applications using

silent uninstallation” on page 40.

twsappsinst

For details, see “Uninstalling IBM Tivoli Workload Scheduler for Applications

and its language pack using twsappsinst” on page 40.

The uninstallation procedure only removes the files that you did not modify.

Before uninstalling

Before you uninstall the product, ensure that the following prerequisites are met:

v You have root permissions on UNIX and administrator permissions on Windows

to run the installation.

v There are no scheduling and SAP monitoring activities currently running for the

application you want to uninstall.

v The installation process is not already running on the workstation. You can

verify this by running one of the following commands:

If you are installing using ISMP

ps -ef | grep setup.bin


ps -ef | grep twsappsinst

v The Option Editor is not running.

Uninstalling


||

Uninstalling the language pack using ISMP wizard

The language pack uninstallation procedure uninstalls all the languages

simultaneously. To uninstall the language pack using the ISMP wizard, perform the

following steps:

1. From the twshome/methods directory, depending on your operating system, run

the following command:

On Windows

.\_lxauninst\uninstaller.exe

On UNIX

./_lxauninst/uninstaller.bin

The ISMP uninstall program starts.

2. Select the language in which you want the wizard to be displayed and click

OK. The Welcome window is displayed.

3. Read the welcome information and click Next.

4. A summary information window is displayed listing all the languages to be

uninstalled. Click Next.

5. The uninstallation process starts. When the uninstallation process has

completed, a window showing the results of the uninstallation is displayed.

Click Finish to complete the uninstallation.

Note: If you launched the uninstaller command from the _lxauninst directory, you

must exit from the _lxauninst directory to complete the uninstallation. In

any case, after the uninstallation completed successfully remove the

_lxauninst directory.

If you received error messages, analyze the /tmp/tws4appslangs_uninst.log file

and the /tmp/TWS4APPS_installationname_LANGS^8.4.log installation log file.

Uninstalling Tivoli Workload Scheduler for Applications using

ISMP wizard

Using the SMP wizard you can uninstall the entire product or one access method

at a time.

To uninstall the product using the ISMP wizard, perform the following steps:

1. From the twshome/methods directory, run the following command:

On Windows

.\_xauninst\uninstaller.exe

On UNIX

./_xauninst/uninstaller.bin

Note: If you upgraded Tivoli Workload Scheduler for Applications to version

8.4, from the twshome/methods directory, run the following command:

On Windows

.\_xauninst2\uninstaller.exe

On UNIX

./_xauninst2/uninstaller.bin

If you do not find the uninstaller run the following command:

java -jar twshome/methods/_xauninst2/uninstall.jar

The ISMP Uninstall program starts.

Uninstalling language pack using ISMP wizard


2. Select the language for the wizard, and click OK. The Welcome window is

displayed.

3. Read the welcome information and click Next.

4. A summary information window is displayed listing all the access methods to

be uninstalled.

5. By default the product uninstalls all the access methods. Clear the access

methods you do not want to uninstall and click Next.

6. The uninstall process starts. When the uninstallation has completed, a window

showing the results is displayed. Click Finish to exit the uninstallation wizard.

Note: If you launched the uninstaller command from the _xauninst directory,

you must exit from the _xauninst directory to complete the

uninstallation. After the uninstallation completed successfully remove the

_xauninst directory.

If you received error messages, analyze the /tmp/tws4apps_uninst_ismp.log and

the /tmp/TWS4APPS_installationname_accessmethod^8.4.log installation log files.

Uninstalling Tivoli Workload Scheduler for Applications or its

language pack using Tivoli Configuration Manager

To uninstall the product or the language pack using Software Distribution, you can

use either the Tivoli Desktop or the wremovsp command. Refer to the IBM Tivoli

Configuration Manager Reference Manual for Software Distribution, version 4.2.1 or later

for detailed information.

To see a list of the packages installed on the workstation by Software Distribution,

use either of the two following procedures:

v Use the Inventory component of Tivoli Configuration Manager version 4.2.1 or

later, to run the query named CM_STATUS_QUERY and list which software packages

are installed on which workstation. Refer to the IBM Tivoli Configuration Manager

User’s Guide for Inventory, version 4.2.1 or later for specific information.

v View the Software Distribution log files on the workstation. Every Software

Distribution package has its own log file. A log file is a text file that records the

installation and uninstallation history of the package. For example, the log file

on an AIX system of the SAP R/3 access method package, r3batch_tws_AIX.log,

is stored in the $BINDIR/../swdis/work directory. To initialize the $BINDIR

environment path of Tivoli Management Framework, launch the following

command:

. /etc/Tivoli/setup_env.sh

Uninstalling the language pack using silent uninstallation

This section describes how to uninstall the Tivoli Workload Scheduler for

Applications language pack using silent uninstallation. Using silent uninstallation,

you can uninstall the language pack without user intervention. To perform this

task, run the following command:

./_lxauninst/uninstaller.bin -silent

When running the uninstallation in silent mode no messages are displayed, but all

messages are written in the /tmp/tws4appslangs_uninst.log and


Uninstalling using ISMP wizard


Uninstalling Tivoli Workload Scheduler for Applications using

silent uninstallation

This section describes how to uninstall Tivoli Workload Scheduler for Applications

using the silent installation. The silent uninstallation enables you to uninstall the

product in silent mode without user intervention.

When running the uninstallation in silent mode no messages are displayed, but all

messages are written in the /tmp/tws4apps_uninst_ismp.log and


To uninstall Tivoli Workload Scheduler for Applications, run the following

command from the twshome/methods directory:

./_xauninst/uninstaller.bin -silent

Uninstalling IBM Tivoli Workload Scheduler for Applications

and its language pack using twsappsinst

To uninstall IBM Tivoli Workload Scheduler for Applications and its language pack

using twsappsinst, perform the following steps:


where you want to uninstall.

2. From the TWShome/methods/xaunist directory, run the twsappsinst script

using the syntax described below. If you received error messages, analyze the

following installation log files:

v /tmp/twsappsinst.log

v /tmp/TWS4APPS_installationname_accessmethod^8.4.log

v /tmp/TWS4APPS_installationname_LANGS^8.4.log



If you want to know the version of the twsappsinst command, run twsappsinst as

follows:


The syntax of the twsappsinst command to uninstall IBM Tivoli Workload

Scheduler for Applications is as follows:

�� twsappsinst -uninst -twsuser user_name �

� -inst_dir


-lang


Table 15 on page 41 describes the twsappsinst parameters used to uninstall IBM

Tivoli Workload Scheduler for Applications:

Uninstalling using silent uninstallation


Table 15. twsappsinst parameters to uninstall IBM Tivoli Workload Scheduler for

Applications


–uninst Yes Uninstalls IBM Tivoli Workload Scheduler for

Applications version 8.4 and its language pack.

–twsuser user_name Yes Specifies the name of the user for which Tivoli

Workload Scheduler is uninstalled. For example: tws84.

The software is uninstalled in this user's home

directory. Enclose the name within double quotes if it

contains a blank.

–inst_dir


No The path to the Tivoli Workload Scheduler installation

where you want to uninstall Tivoli Workload Scheduler

for Applications. The software is installed by default in

the user's home directory, referred to as TWShome. For

example: /home/tws84/tws. Enclose the name within

double quotes if it contains a blank.

–lang

messages_language

No The language in which the twsappsinst uninstallation

messages are displayed. If not specified, the system

LANG is used. If the related catalog is missing, the

default C language catalog is used. Possible values are:

de German

it Italian

es Spanish

fr French

ko Korean

ja Japanese




Example to uninstall Tivoli Workload Scheduler for Applications

version 8.4 using twsappsinst

Following is an example of how to uninstall Tivoli Workload Scheduler for

Applications version 8.4 using twsappsinst:

twsappsinst -uninst -twsuser tws84 -inst_dir /home/tws84/tws

Completing the removal of the access method for Oracle

E-Business Suite

For the Oracle E-Business Suite access method, when the uninstallation process has

completed, perform the following steps:

1. Restore APPLSYS.env to its original contents by removing the MCM string from

the APPLSHAR and APPLFUL variables. For example:

APPLSHAR=’ALR FF MCM’

becomes:

APPLSHAR=’ALR FF’

2. Remove the following files:

v TWShome/methods/MCMAGENT

v TWShome/catalog/C/mcm.cat

v MCMLJ, MCMSTAT, and MCMTJ located in the $MCM_TOP/bin directory

v MCMLJ.O, MCMSTAT.O, and MCMTJ.O located in the $MCM_TOP/LIB directory

v MCMprod.txt located in the $APPL_TOP/admin directory

v All the options files

Uninstalling using twsappsinst


Completing removal of the Oracle E-Business Suite access method


Chapter 3. Setting options with the Option Editor

An options file is a text file containing a set of options to customize the behavior

of the access method when submitting a job. The options must be written one per

line and have the following format (with no spaces included):

option=value

All access methods use two types of options files:

Global options file

A common configuration file created by default for each access method

installed, whose settings apply to all the extended agent workstations defined

for that method. When the global options file is created, it contains only the

LJuser option, which represents the operating system user ID used to launch

the access method. You can customize the global options file by adding the

options appropriate to the access method.

The name of the global options file is accessmethod.opts, which, depending on

your operating system, corresponds to:

For Oracle E-Business Suite MCMAGENT.opts

For PeopleSoft psagent.opts

For SAP R/3 r3batch.opts

For z/OS mvsca7.opts, mvsjes.opts, mvsopc.opts

Local options file

A configuration file that is specific to each extended agent workstation within a

particular installation of an access method. The name of this file is

WORKSTATIONNAME_accessmethod.opts, where WORKSTATIONNAME is the name

of the extended agent. If you do not create a local options file, the global

options file is used. Every extended agent workstation, except for z/OS, must

have a local options file with its own configuration options.

Note: WORKSTATIONNAME must be written in uppercase characters and

cannot contain DBCS characters.

For example, if the installation of the access method for SAP R/3 includes two

extended agent workstations, CPU1 and CPU2, the names of the local options files

are respectively CPU1_r3batch.opts and CPU2_r3batch.opts.

The files must reside in the methods subdirectory of the Tivoli Workload Scheduler

installation and are read when the extended agent is initialized. Options are

specific to each access method. To know the options of each access method, see:

v Chapter 7, “Configuring the Oracle E-Business Suite access method,” on page 63

for Oracle

v Chapter 10, “Configuring the PeopleSoft access method,” on page 75 for

PeopleSoft

v Chapter 14, “Configuring the SAP R/3 access method,” on page 103 for SAP R/3

v Chapter 26, “Configuring the z/OS access method,” on page 221 for z/OS

To modify a local or global options file, or create a local options files, you can

either use a text editor or the Option Editor described in “Using the Option

Editor” on page 44.


||

Before completing installation, Tivoli Workload Scheduler for Applications

optionally starts the Option Editor to let you define local options, while some of

the values you entered during the process are used to create a global options file.

Option value inheritance

This property is currently available for r3batch only. Local options files can inherit

existing values from the same options in the global options file (r3batch.opts). For

an access method the options are listed twice: once as global options and once as

local options. If the local options file does not contain a value for the option, then

the value for that option in the global options file is used. Otherwise the option

value in the local options file is always used.

For example, you might want to define the same value for the Ljuser option and a

different value for the retrive_joblog option. To do this, you define the Ljuser

option value in the r3batch.opts file. Then you define a different value for the

retrive_joblog option in each local options file. This results in the following when

launching the SAP R/3 job:

v The value for the Ljuser option is extracted from the r3batch.opts file.

v The value for the retrive_joblog option is taken from each local options file.

Using the Option Editor

This section describes the Option Editor and how to use it to perform the

following tasks:

v Modify local or global options file. See “Modifying local or global options files”

on page 46 for a detailed explanation.

v Create a local options file. See “Creating local options files” on page 46 for a

detailed explanation.

To start the Option Editor, go to the TWShome/methods directory of your Tivoli

Workload Scheduler installation and, depending on you operating system, run the

following command:

On Windows opted.exe

On UNIX opted.bin

Note: To use the Option Editor on a UNIX workstation, you must

have a graphical environment.

The Option Editor automatically loads all the existing global and local options files

grouped by access method.

The Option Editor window has three main areas, as shown in Figure 3 on page 45.

To choose which areas you want to see, select View→Show. The areas are:

File Options Tree

Shows a list of all the existing options files, grouped by method.

Option Descriptor

Gives a description of the current selection.

File Options View

Displays the options of a selected file in any of the three available views.

Setting options with the Option Editor


The Option Editor provides three possible views of an options file. To change the

view in which the options file is displayed select View→Display As. The views are:

Simple

Displays the options as a sequence of tabs that you can select to edit one

option at a time. To view or edit an option, select the tab with the option

name to display the field for the value. This is the easiest way to edit

options, because you only see the actual value that is used in the file.

Inherited or default values are not displayed.

Table Provides a tabular view of all the options for a selected file. This is the

default view. For each option the following columns are displayed:

Name

The name of the option.

Value

The value specified in the file.

Default Value

The value used by the method if not specified in the options file or

inherited.

Inherited Value

The value obtained from the global options file if inheritance is

supported by the access method. See “Option value inheritance” on

page 44 for a detailed explanation.

Actual Value

The value actually used at run time. The values are used in the order:

value, if available; inherited value, if supported; default value.

Options Files Tree

Option DescriptorFile Options View

Figure 3. The Option Editor


Chapter 3. Setting options with the Option Editor 45

Text Displays an options file in the typical format, showing only the options

that have a value. This view is generally used for preview purposes,

because files are shown in read-only form. Password fields are shown

encrypted.

Mandatory options are identified by a yellow background and are marked with an

asterisk (*). Options that are not correctly entered are shown with a red

background. The Option Editor performs only syntactic checks.

Ensure that the Option Editor is not running before you add or update an existing

Tivoli Workload Scheduler for Applications installation.

You should restrict access to the Option Editor. If you have multiple installations of

an extended agent, you can increase security by maintaining only one copy of the

Option Editor, for example, on the master workstation.

Modifying local or global options files

To modify local or global options files, using the Option Editor, perform the

following steps:

1. From the File Options Tree area, select the options file you want to modify.

The options are displayed in the File Options View area.

2. Select the option you want to modify and modify its value.

3. Save and close the options file.

Creating local options files

While global options files are created each time you install an access method, you

create local options files when you define a new extended agent workstation. To

create a local options file, using the Option Editor, perform the following steps:

1. Click File→New in the menu bar. The New Option File window is displayed.

2. In the Insert XA CPU Name field, enter the name of the extended agent

workstation for which you want to create an options file.

3. Select an access method from the Insert Method Name drop-down menu. The

new options file has the following name: WORKSTATION_accessmethod.opts

where:

WORKSTATION

The name you specified in the Insert XA CPU Name field.

accessmethod

The access method you selected from the Insert Method Name drop-down

menu4. Enter values for the options you want to define.

5. Save and close the options file.



Chapter 4. Defining extended agent workstations

An extended agent workstation definition is required for each entity of an access

method through which Tivoli Workload Scheduler schedules and lunches jobs.

Extended agent workstations are defined in the standard manner and include the

name of the extended agent host and the method name.

To launch a job on an extended agent workstation, Tivoli Workload Scheduler runs

the access method, passing it information about the job. The access method

communicates with the instance of the particular Oracle E-Business Suite,

PeopleSoft, SAP R/3, or z/OS system and monitors the job through completion,

writing job progress and status information to the job’s standard list file.

Creating a workstation using the Job Scheduling Console

To define an extended agent workstation with the Job Scheduling Console, perform


1. In the Actions list of the Job Scheduling Console main window, select New

Workstation.

2. Select an engine. The Properties - Workstation in Database panel is displayed.


3. Complete the fields using the information in Table 16 on page 49.

4. Click OK to save and close the panel.

Table 16 on page 49 shows how to complete the fields of the workstation properties

panel depending on which extended agent workstation you are defining.

Figure 4. Defining a workstation using the Job Scheduling Console



Table 16. How to complete the fields of the Properties - Workstation in Database panel

Field Description by Access Method

PeopleSoft z/OS Oracle E-Business

Suite

SAP R/3

Ignore Select this option only if you want Tivoli Workload Scheduler to ignore this workstation

definition. It is useful if you want to predefine job streams, jobs, and objects for a system

that has not yet been installed.

Name The name for the extended agent workstation. For all access methods (except the one for

z/OS which always has a limit of 8 characters), the name must start with a letter and can

contain alphanumeric characters, dashes, and underscores. The maximum length is 16

characters. Workstation names must be unique and cannot be the same as workstation class

and domain names.

For all the access methods, this name must be consistent with the name of the options file

associated with the workstation. That is, if the options file name is

<myworkstation>_<mymethod>.opts, then myworkstation and Name must be the same.

Domain The name of the Tivoli Workload Scheduler domain of the host workstation. The name must

start with a letter and can contain alphanumeric characters, dashes, and underscores. The

maximum length is 16 characters. Domain names must be unique and cannot be the same as

workstation and workstation class names. Click ellipsis (...) to display a list of existing

domains.

Use Master Select it to specify that the host workstation is in the same domain as the master domain

manager.

Description An optional free-form textual description of the workstation. The maximum length is 120

characters.

Workstation Type Select Extended Agent.

Operating System Select Other.

Full Status Not used on extended agent workstations.

Time Zone The time zone of the workstation. If the Tivoli Workload Scheduler network is using the

Time Zone option, select the appropriate time zone from the drop-down list. Leave the field

blank, if this is not the case. For a description of time zone names, refer to the Tivoli

Workload Scheduler: User's Guide and Reference. To ensure the accuracy of scheduling times,

this time zone must be the same as the workstation operating system time zone. The Time

Zone feature is enabled using the optman command. Refer to the Tivoli Workload Scheduler:

Planning and Installation Guide.

Node Name null The node name or IP

address of the z/OS

system. Fully

qualified domain

names are accepted.

null null

TCP Port Any number other

than 0.

The TCP/IP address

(port number) of the

z/OS gateway on the

z/OS system. Enter

the same value as the

SYSTSIN variable

PORT described in

Table 57 on page 213.

Any number other than

0.

Any number other

than 0.

SSL Communication Not used on extended agent workstations.

SSL Port Not used on extended agent workstations.

Mailman Server Not used on extended agent workstations.

Behind Firewall Not used on extended agent workstations.


Chapter 4. Defining extended agent workstations 49

Table 16. How to complete the fields of the Properties - Workstation in Database panel (continued)

Field Description by Access Method

PeopleSoft z/OS Oracle E-Business

Suite

SAP R/3

AutoLink Not used on extended agent workstations.

Access Method psagent Depending on your

job scheduling

interface, one of the

following:

mvsca7

To launch and

monitor z/OS jobs

using CA-7.

mvsjes

To launch and

monitor z/OS jobs

using JES2 or JES3.

mvsopc

To launch and

monitor z/OS jobs

using Tivoli

Workload

Scheduler for

z/OS.Note: In UNIX the

name is case sensitive

and must be in

lowercase.

MCMAGENT

Note: The name is case

sensitive and must be

in uppercase.

r3batch

Note: In UNIX the

name is case

sensitive and must

be in lowercase.

Host The Tivoli Workload Scheduler name of the host system. This is the Tivoli Workload

Scheduler fault-tolerant agent or standard agent on which the extended agent is installed.

Click ellipsis (...) to see a list of existing hosts.

Creating a workstation using the command line

Extended agent workstation definitions can also be made on the Tivoli Workload

Scheduler command line using the composer program. The following example

shows a definition for a z/OS extended agent workstation named MVSCPU that

uses the mvsjes access method.

cpuname MVSCPU description "zOS extended agent"

os other

node mvsesa36.rome.tivoli.com

tcpaddr 5000

domain masterdm

for maestro

type x-agent

host ROCIOUS

access mvsjes

end

For further details about defining workstations with composer, refer to the IBM

Tivoli Workload Scheduler Reference Guide.



Defining workstations for end-to-end scheduling

Scheduling in an end-to-end environment means that in Tivoli Workload Scheduler

for z/OS you are scheduling and monitoring jobs that are physically running on

Tivoli Workload Scheduler workstations.

Extended agent workstations must be defined as fault-tolerant workstations in

Tivoli Workload Scheduler for z/OS.

A fault-tolerant workstation is the Tivoli Workload Scheduler for z/OS definition

of an existing Tivoli Workload Scheduler agent in the distributed network. The

Tivoli Workload Scheduler agent is where the job associated with the fault-tolerant

workstation actually runs in the distributed network.

To define the extended agent workstation in Tivoli Workload Scheduler for z/OS,

you must:

1. Define the workstation in the CPUREC initialization statement.

2. Add the same workstation definition to the database using ISPF or the Job

Scheduling Console. For a description of how to define the workstation using

the Job Scheduling Console, refer to the Tivoli Job Scheduling Console User’s

Guide.

Creating the CPUREC statement

Create the CPUREC statement for the workstation in the TOPOLOGY initialization

statement. The TOPOLOGY initialization statement is used to define parameters

related to the topology of the connected Tivoli Workload Scheduler network. Such

a network topology statement is made up of one or more (one for each domain)

DOMREC statements that describe the topology of the distributed network, and by

several CPUREC statements, one for each fault-tolerant workstation.

The following example shows a CPUREC statement for an SAP R/3 extended agent

workstation named R3XA. The extended agent is hosted by a Tivoli Workload

Scheduler agent named TWSA, which is also the domain manager of DOMAIN1.

****************TPLGINFO MEMBER ***************************

/*********************************************************************/

/* DOMREC: Domain definition */

/*********************************************************************/

DOMREC DOMAIN(DOMAIN1)

DOMMNGR(TWSA)

DOMPARENT(MASTERDM)

/*********************************************************************/

/* CPUREC: Extended agent workstation definition */

/*********************************************************************/

CPUREC CPUNAME(R3XA)

CPUOS(OTHER)

CPUNODE(NODE1)

CPUDOMAIN(DOMAIN1)

CPUHOST(TWSA)

CPUTYPE(XAGENT)

CPUACCESS(r3batch)

CPUUSER(TWSuser)

CPUTZ(’Europe/Rome’)

/*********************************************************************/

/* CPUREC: Domain manager workstation definition */

/*********************************************************************/

CPUREC CPUNAME(TWSA)

CPUNODE(NODE1)

CPUAUTOLINK(ON)

Defining workstations for end-to-end scheduling

Chapter 4. Defining extended agent workstations 51

CPUDOMAIN(DOMAIN1)

CPUTYPE(FTA)

CPUUSER(TWSuser)

CPUTZ(’Europe/Rome’)

The following keywords define R3XA as an extended agent:

CPUACCESS The extended agent access method. For SAP R/3, it is r3batch.

CPUHOST The name of the Tivoli Workload Scheduler workstation hosting

the extended agent. It cannot be another standard agent or

extended agent.

CPUTYPE The workstation type. For an extended agent, it must be XAGENT.

For further information on CPUREC, see Tivoli Workload Scheduler for z/OS

Customization and Tuning.

Defining the workstation with ISPF

Figure 5 shows the ISPF definition for R3XA.

In ISPF (and in the Job Scheduling Console), define the workstation as computer

automatic and then set the FT Work station field to Y. It is the CPUREC statement

with the three keywords described in “Creating the CPUREC statement” on page

51 that provides the extended agent specification.

Note: Make sure you write the CPUREC statement before making the ISPF or Job

Scheduling Console definition, because they alone have no effect without the

CPUREC statement.

-------------- CREATING GENERAL INFORMATION ABOUT A W0RK STATION --------------

Command ===>

Enter the command R for resources A for availability or M for access method

above, or enter data below:

WORK STATION NAME ===> R3XA

DESCRIPTION ===> Extended agent for R/3 access method____________________

WORK STATION TYPE ===> C G General, C Computer, P Printer

REPORTING ATTR ===> A A Automatic, S Manual start and completion

C Completion only, N Non reporting

FT Work station ===> Y FT Work station, Y or N

PRINTOUT ROUTING ===> SYSPRINT The ddname of daily plan printout data set

SERVER USAGE ===> N Parallel server usage C , P , B or N

Options:

SPLITTABLE ===> N Interruption of operation allowed, Y or N

JOB SETUP ===> N Editing of JCL allowed, Y or N

STARTED TASK, STC ===> N Started task support, Y or N

WTO ===> N Automatic WTO, Y or N

DESTINATION ===> ________ Name of destination

Defaults:

TRANSPORT TIME ===> 00.00 Time from previous work station HH.MM

DURATION ===> ________ Duration for a normal operation HH.MM.SS

Figure 5. Defining an Extended Agent workstation

Creating the CPUREC statement


Chapter 5. Defining extended agent jobs

This chapter describes how to define the Tivoli Workload Scheduler jobs associated

with the external jobs you want to run through the extended agents.

To run and monitor a PeopleSoft, SAP R/3, Oracle, or z/OS job with Tivoli

Workload Scheduler, the extended agent (or access method) requires a Tivoli

Workload Scheduler job definition, where you specify the external job you want to

schedule, the workstation (also defined in Tivoli Workload Scheduler) on which it

is to run, and any recovery actions. To define the job, you can use either of the

following:

v The Tivoli Job Scheduling Console

v The Tivoli Workload Scheduler command line

If you are scheduling in an end-to-end environment, you must use the Tivoli

Workload Scheduler for z/OS ISPF dialogs to define the job. You must also create a

member in the SCRIPTLIB with a JOBREC statement for the job.

Extended agent jobs are added to job streams and scheduled in the same way as

any other job in Tivoli Workload Scheduler and Tivoli Workload Scheduler for

z/OS.

Defining jobs with the Job Scheduling Console

The steps described here for defining an extended agent job are common to all

access methods. Also, the access method for SAP R/3 provides supplementary

features if you use the alternative steps described in “R/3 Job page” on page 121.

For all access methods, follow these steps:

1. In the Actions list of the Job Scheduling Console main window, select New Job

Definition.

2. Select an engine. The General page of the Properties - Job Definition panel is

displayed.


The panel consists of the following:

v “General page”

v “Task page” on page 56

General page

Use the General page to provide general information about the new job definition.

The page consists of the following:

v Information group:

Task Type

From the pull-down menu, select one of the following:

Other The job is a Tivoli Workload Scheduler job that runs a job belonging

to one of the following applications:

– PeopleSoft


– z/OS

SAP The job is a Tivoli Workload Scheduler job that runs an SAP R/3 job.

The SAP task type is displayed only if you installed the extended

agent for SAP R/3. For detailed information see Chapter 15,

“Managing the running of SAP jobs,” on page 115.

Figure 6. The General Page of the Properties - Job Definition panel

Defining jobs with the Job Scheduling Console


Name

Type the name of the Tivoli Workload Scheduler job that runs the external

application job whose name you provide in the Job Name field of the Task

page. The name must start with a letter, and can contain alphanumeric

characters, dashes, and underscores. The maximum length is 40 characters. It

can be the same as the external job name, as long as it is valid in Tivoli

Workload Scheduler.

Workstation Name

Type the name of the extended agent workstation where the Tivoli Workload

Scheduler job runs or use ellipsis (...) to display a list of workstations.

Description

Type a description of the job. The maximum length is 120 characters.v Login group:

Login

Type the name of the user who launches the job. The maximum length is 47

characters. Specify a user that can log on to the workstation where the job

runs. Normally, this is the value of the LJuser parameter, specified during

the installation of Tivoli Workload Scheduler for Applications, that is in the

options file for the method. This must be a valid user on the Tivoli Workload

Scheduler host workstation who must also be able to access the external

product. For more information, see Tivoli Workload Scheduler: Job Scheduling

Console User’s Guide.

Add Parameter

Adds a parameter to the login field.v Recovery Options group:

From the pull-down menu, select the recovery option you want to associate with

the job if it ends in error. Possible values are:

Stop Do not continue with the next job. This is the default value.

Continue Continue with the next job.

Rerun Rerun the job.

Message

Type the text of a recovery prompt to be displayed if the job ends in error.

The text can contain up to 64 characters. The recovery prompt is an ad hoc

prompt. The Status of All Prompts shows all recovery prompts. If a job

ended in error, the prompt status is Asked and the message is displayed. If a

job ended successfully, the status is Not Asked.

Job

Click ellipsis (...) to display a list of recovery jobs from which to select the

recovery job to run if the job you are defining ends in error. Recovery jobs

are run only once for each instance of the job.

Workstation Name

Displays the name of the workstation where the recovery job runs. The name

is entered automatically when you select a recovery job.

Not all jobs are eligible to have recovery jobs run on a different workstation.

Follow these guidelines:

– If either workstation is an extended agent, it must be hosted by a domain

manager or a fault-tolerant agent that runs in Full Status mode.

– The recovery job workstation must be in the same domain as the parent

job workstation.

General page

Chapter 5. Defining extended agent jobs 55

– If the recovery job workstation is a fault-tolerant agent, it must run in Full

Status mode.

Task page

Use the Task page to provide task information for the external job that is run by

the Tivoli Workload Scheduler job defined in the General page. This page is not

available until a workstation has been specified in the General page.

The content of the task page depends on the task type you selected. If you selected

Other, provide the following information; if you selected SAP, proceed as

described in “Task page” on page 118.

Script When the task is a script, this is the file name and any options and

arguments. The maximum length is 4095 characters. Do not specify files on

mapped drives. If the file name contains blanks, type the name in a file

that does not have spaces and use the second file. Do not use double

quotes (″).

v For Oracle Applications jobs, see “Task string parameters for Oracle

E-Business Suite jobs” on page 67.

v For Peoplesoft jobs, see “Task string parameters for PeopleSoft jobs” on

page 83.

v For SAP R/3 jobs, see “Task string to define SAP jobs” on page 129.

v For z/OS jobs, see “Task definition syntax for z/OS jobs scheduled with

Tivoli Workload Scheduler” on page 223.

Write the parameters in a string having the following format:

-parameter1 value1 -parameter2 value2...-parametern valuen

Figure 7. The Task Page of the Properties - Job Definition panel

General page


Clicking on Add Parameter.... The Find Parameters panel displays where

you can list and add pre-defined Tivoli Workload Scheduler parameters to

the Script field.

Return Code Mapping Expression

The return codes that cause the job to be successful. Enter a logical

expression that defines the success condition. Allowed operators are

comparison operators (=, != or <>, >, >=, <, <=) and logical operators

(AND, OR, NOT). For a detailed description about how Tivoli Workload

Scheduler calculates the return code mapping for PeopleSoft, see

“Configuring the job status mapping policy” on page 85. For a detailed

description about how Tivoli Workload Scheduler calculates the return

code mapping for SAP R/3 and Oracle E-Business Suite, see Chapter 28,

“The return code mapping feature,” on page 239.

Defining jobs using the Tivoli Workload Scheduler command line

You can also be define jobs using the composer command line of Tivoli Workload

Scheduler. The following example describes a Tivoli Workload Scheduler job

named orajob2 that runs in an Oracle Applications extended agent workstation

named ora002. It logs on to UNIX as orajobs and launches a job under Oracle

Applications. The Oracle Applications job is named poxacr and its owner is global.

If recovery is needed, Tivoli Workload Scheduler will run job recov2 and then

continue processing.

ora002#orajob2

streamlogon orajobs

scriptname "-user global

-job fnd ’application developer’ po poxacr

-prn ps4 2

-v1 ’abc’"

description "oracle apps job #2"

recovery continue after recov2

The arguments of scriptname differ by application. For details, see:

v “Task string parameters for Oracle E-Business Suite jobs” on page 67.

v “Task string parameters for PeopleSoft jobs” on page 83.

v “Task string to define SAP jobs” on page 129.

v “Task definition syntax for z/OS jobs scheduled with Tivoli Workload

Scheduler” on page 223.

For more information about using the command line to define jobs, refer to the


Defining jobs for end-to-end scheduling

Extended agent jobs scheduled to run in an end-to-end environment cannot be

defined using the Job Scheduling Console or the Tivoli Workload Scheduler

command line, but must be added to the SCRIPTLIB of Tivoli Workload Scheduler

for z/OS.

In the OPERATIONS ISPF panel of Tivoli Workload Scheduler for z/OS, extended

agent jobs are defined like any other job, but the choice of an extended agent

workstation denotes their kind. The following example shows the definition of a

job named SAPJOB. This is the Tivoli Workload Scheduler for z/OS job that is to

drive the running of an SAP R/3 job (named BAPRINT46B as shown in the next

example). It shows as an extended agent job because the associated workstation is

General page

Chapter 5. Defining extended agent jobs 57

an extended agent workstation named R3XA.

For each job, create a member in the SCRIPTLIB of Tivoli Workload Scheduler for

z/OS with details about the job in a JOBREC statement. A SAPJOB member was

created for the job of the previous example. It contains a JOBREC statement like this:

JOBREC

JOBCMD(’/-job BAPRINT46B -user MAESTRO -i 14160001 -c C’)

JOBUSR(twsila)

The string in JOBCMD is read and interpreted by the access method prior to running

the job. The job of this example, BAPRINT46B, was previously defined on SAP R/3

and assigned with an ID of 14160001, that was manually written in JOBCMD.

The following example is for a PeopleSoft job. The entire string that follows the

JOBCMD keyword must be enclosed within double quotation marks, because for

PeopleSoft jobs single quotes are already used in the string.

JOBREC

JOBCMD("/ -process XRFWIN -type ’SQR Report’ -runcontrol TWS")

JOBUSR(PsBuild)

The arguments of JOBCMD differ by application. For details, see:

v “Task string parameters for Oracle E-Business Suite jobs” on page 67.

v “Task string parameters for PeopleSoft jobs” on page 83.

v “Task string to define SAP jobs” on page 129 or Chapter 17, “Defining SAP jobs

dynamically,” on page 149.

v “Task definition syntax for z/OS jobs scheduled with Tivoli Workload

Scheduler” on page 223.

Submitting extended agent jobs

To submit extended agent jobs perform the following steps:

1. Verify that the application system to which the job belongs and the related

database is up and running.

2. Launch the job. For details, refer to the Tivoli Workload Scheduler

documentation.

--------------------------------- OPERATIONS -----------------Row 1 to 1 of 1

Command ===> Scroll ===> PAGE

Enter/Change data in the rows, and/or enter any of the following

row commands:

I(nn) - Insert, R(nn),RR(nn) - Repeat, D(nn),DD - Delete

S - Select operation details, J - Edit JCL

Enter the TEXT command above to include operation text in this list, or,

enter the GRAPH command to view the list graphically.

Application : APLL1 FTW appl

Row Oper Duration Job name Internal predecessors Morepreds

cmd ws no. HH.MM.SS -IntExt-

’’’’ R3XA 001 00.00.01 SAPJOB___ ___ ___ ___ ___ ___ ___ ___ ___ 0 0

******************************* Bottom of data ********************************

Figure 8. Defining an Extended Agent job for end-to-end scheduling

Defining jobs for end-to-end scheduling





Chapter 6. Introducing Tivoli Workload Scheduler for

Applications for Oracle E-Business Suite

Using Tivoli Workload Scheduler for Applications for Oracle E-Business Suite you

can schedule Oracle E-Business Suite jobs using Tivoli Workload Scheduler.

The Tivoli Workload Scheduler host, Tivoli Workload Scheduler extended agent for

Oracle E-Business Suite, and Oracle E-Business Suite instance must be installed on

the same physical node.

Software requirements

In addition to the supported operating systems and prerequisite software listed in

Chapter 2, “Installing, upgrading, and uninstalling IBM Tivoli Workload Scheduler

for Applications,” on page 5, you must have Oracle Applications version 10.7 or

Oracle E-Business Suite versions 11.0 or 11.i installed.

Note: The procedure described in this part refers to Oracle E-Business Suite and

applies both to Oracle Applications version 10.7 and to Oracle E-Business

Suite versions 11.0 or 11.i, unless otherwise specified.

Features

Using Tivoli Workload Scheduler for Applications for Oracle E-Business Suite, you

can perform the following tasks:

v Use Tivoli Workload Scheduler standard job dependencies (except Open File

dependencies).

v Schedule Oracle E-Business Suite jobs to run on specified days, times, and in a

prescribed order.

v Define inter-dependencies between Oracle Applications jobs and jobs that run on

different systems such as SAP R/3 and PeopleSoft.

v Define inter-dependencies between Oracle Applications jobs and jobs that run on

different operating systems.

v Customize job execution return codes.

Roles and responsibilities

In a typical enterprise, different users contribute to the implementation and

operation of the product. Table 17 describes the roles and responsibilities of all

actors in the process model, showing the tasks they perform.

Table 17. Roles and responsibilities in Tivoli Workload Scheduler for Applications for Oracle

E-Business Suite

User role User task

Oracle E-Business Suite

administrator

“Completing the installation of the access method for

Oracle E-Business Suite” on page 31

Oracle E-Business Suite developer “Defining jobs in Oracle E-Business Suite” on page

67


Applications configurator

“Defining the configuration options” on page 63


|

|||

|||

||

||||

|||

|||

Table 17. Roles and responsibilities in Tivoli Workload Scheduler for Applications for Oracle

E-Business Suite (continued)

User role User task


Applications developer

“Defining Oracle E-Business Suite jobs in Tivoli

Workload Scheduler” on page 67

Interface software

The interface between Tivoli Workload Scheduler and Oracle E-Business Suite

comprises the following software:

Front-end

MCMAGENT The Tivoli Workload Scheduler for Applications for Oracle

E-Business Suite access method. Use this to prepare a job for

launching. When you launch, monitor and, optionally, stop the

job, using the options of the method, the method launches one

of the back-end programs to accomplish the task.

Back-end

MCMLJ A program that submits a job to Oracle Concurrent Manager.

MCMSTAT A program that monitors the status of the submitted job.

MCMTJ A program that stops the submitted job on receiving a kill

signal from Tivoli Workload Scheduler.

mcm.mk A makefile utility for linking the above programs with Oracle

E-Business Suite.

Options

MCMAGENT.opts

A global options file which contains configuration settings for the

access method. It is created by the installation process of Tivoli

Workload Scheduler for Applications with some of the values you enter

during installation. See Chapter 7, “Configuring the Oracle E-Business

Suite access method,” on page 63 and Chapter 3, “Setting options with

the Option Editor,” on page 43 for details.

WORKSTATION_ NAME_MCMAGENT.opts

A local options file which contains configuration settings for the

extended agent. One file is required for each extended agent

workstation that you define. See Chapter 7, “Configuring the Oracle

E-Business Suite access method,” on page 63 and Chapter 3, “Setting

options with the Option Editor,” on page 43 for details.

Features


||

||

|||||

|

Chapter 7. Configuring the Oracle E-Business Suite access

method

This chapter provides detailed reference information about the Tivoli Workload

Scheduler for Applications for Oracle E-Business Suite options file.

Defining the configuration options

The Tivoli Workload Scheduler for Applications installation process creates a

default global options file for the Oracle E-Business Suite access method, named

MCMAGENT.opts. You can also create local files, named

WORKSTATIONNAME_MCMAGENT.opts, which must be located in the TWShome/methods

directory of the hosting computer for the extended agent.

To edit both options files, you can use either the Option Editor available with this

product, or any other text editor. For details about how to create and edit the

options files with the Option Editor, see Chapter 3, “Setting options with the

Option Editor,” on page 43. For examples of an options file for this access method,

see “Examples” on page 65.

If you do not create a local options file, the agent uses, by default, the global

options file.

Table 18 lists the options that you can define for the MCMAGENT access method.

The options must be written one per line and have the following format (with no

spaces included):

OPTION=VALUE

Table 18. MCMAGENT access method options

Option Description

CFUSER (Mandatory) Assigns the user name used by the access

method to check file dependencies (CF tasks). It can be the

same as LJUSER.

ENV (Mandatory) The environment file to run. Each instance of

Oracle E-Business Suite has its own environment file

(APPLSYS.env or APPDEMO.env). The .env filename

identified here is used to set the environment dynamically

when Tivoli Workload Scheduler runs jobs on the Oracle

Applications extended agent.

FND_TOPDIR (Mandatory) The FND top directory where the Oracle

E-Business Suite Object Library resides.


||||

Table 18. MCMAGENT access method options (continued)

Option Description

MAX_TIME (Mandatory) This acts as the maximum increment of the job

status polling interval. The job status polling interval is

incremented each polling cycle (see MIN_TIME). When the

interval reaches or exceeds the value of this option, it

remains at this value. It is expressed in seconds.

Use MIN_TIME and MAX_TIME to poll for status

information more frequently when the job has just started

(helping you to catch an immediate job failure as soon as

possible, for example), and then change to a longer interval

for jobs that are expected to take some time before

completion.

MIN_TIME (Mandatory) This value is used as both the initial job status

polling interval, and as the incremental value by which the

polling interval is increased each polling cycle. It is

expressed in seconds.

Use MIN_TIME and MAX_TIME to poll for status

information more frequently when the job has just started

(helping you to catch an immediate job failure as soon as

possible, for example), and then change to a longer interval

for jobs that are expected to take some time before

completion.

ORA_APP_TOPDIR (Mandatory) The UNIX directory where Oracle E-Business

Suite is installed.

ORACLE_HOME (Mandatory) The UNIX directory where Oracle E-Business

Suite is installed.

ORACLE_SID (Mandatory) The Oracle system identifier of the database

instance you are connecting to. This corresponds to the

value of the Oracle E-Business Suite$ORACLE_SID variable.

PASSWORD (Mandatory) The password for the selected user ID. It must

be encrypted. To encrypt the password use the enigma

utility, provided with the product. For details, see

“Encrypting Oracle E-Business Suite user passwords” on

page 66.

PATH (Mandatory) The setting of the PATH variable, including

the existing path, the path to the bin directory of Oracle

E-Business Suite, the path to the include directory under

the FND Top directory, and others as needed.

PRINTER_NAME (Mandatory) The default printer ID.

THREE_TIER_DB (Optional) Allows the extended agent to function in a

three-tier Oracle connectivity environment.

Supply the TNS service name defined in the Oracle

environment pointing to a remote database server. See the

sample options file shown in “Examples” on page 65.

TWSMETH_CP (Optional) The code page that the MCMAGENT access

method uses to write its output.

This option must be consistent with TWSMETH_LANG. It

can be any of the existing TIS codepages.

TWSMETH_LANG (Optional) The language used to report messages.

This option must be consistent with TWSMETH_CP.

Defining the Oracle E-Business Suite configuration options


|||||

|||

||

||

|

Table 18. MCMAGENT access method options (continued)

Option Description

TWSXA_CP (Optional) Specifies the encoding character set of the Oracle

E-Business Suite database. The default value is the default

code set of the operating system.

USERID (Mandatory) A database user ID that has access to all the

modules in Oracle E-Business Suite. It must be able to

launch, manage, and terminate jobs in Oracle E-Business

Suite.

UTF8CMDLINE (Optional) Enables the encoding of the extended parameters

in UTF-8 format. Specify 1 to enable the option, or 0 to

disable it. The default value is 0, meaning that the code set

of the operating system is used.

Examples

File ORACLECPU_MCMAGENT.opts is a sample options file:

ORACLE_HOME=/general/ora716

ORACLE_SID=DEMO106

ORA_APP_TOPDIR=/apps106

FND_TOPDIR=$APPL_TOP/fnd/*

PATH=$PATH:$ORACLE_HOME/bin:$FND_TOP/include

ENV=$APPL_TOP/APPDEMO106.env

USERID=APPS_US

PASSWORD=APPS_US

PRINTER_NAME=PRINTER1

MIN_TIME=10

MAX_TIME=200

The following example shows the options file of an extended agent configured for

an Oracle three-tier connectivity environment. In this example, TST is the name of

the Oracle database instance where the Oracle E-Business Suite database is located

and REMOTEDB is the TNS Oracle service name.

MIN_TIME=10

ORACLE_HOME=/oracle/db/TST

ORACLE_SID=TST

ORA_APP_TOPDIR=/oracle/Apps11

FND_TOPDIR=$APPL_TOP/fnd/11.0.28

PATH=$PATH:$FND_TOP/bin:$MCM_TOP/bin

ENV=$APPL_TOP/APPTST.env

USERID=apps

PASSWORD=##3Y-UGcZ-3Kap-6m

PRINTER_NAME=prt4b2

MAX_TIME=150

THREE_TIER_DB=REMOTEDB

The following example shows the encoding options to set for an Oracle E-Business

Suite database that uses the code page UTF8 so that it can process a job whose task

string contains Japanese characters.

UTF8CMDLINE=1

TWSXA_CP=UTF8

Defining the Oracle E-Business Suite configuration options

Chapter 7. Configuring the Oracle E-Business Suite access method 65

||||

|||||

|||

||

Encrypting Oracle E-Business Suite user passwords

When you make entries in the options file, the password value is automatically

encrypted before it is written to the file. If you modify the file with a text editor,

you must run the enigma program to encrypt the password before writing it to the

file. Run the enigma program as follows:

enigma [password]

You can include the password on the command line or enter it in the response to a

prompt. The program returns an encrypted version that you can then enter in the

options file.

With Tivoli Workload Scheduler for Applications version 8.4, a new algorithm is

applied to encrypt the password that is stored in the options file. When you use

enigma, pwdcrypt, or the Option Editor the password is encrypted by applying

this new algorithm. It is also applied if you open and save the options file with the

Option Editor. The old password encryption is still recognized and processed by

Tivoli Workload Scheduler for Applications version 8.4, so you do not need to

encrypt the password again.

Encrypting Oracle E-Business Suite user passwords


|||||||

Chapter 8. Defining Oracle E-Business Suite jobs

This chapter provides information for defining Oracle E-Business Suite jobs in

Tivoli Workload Scheduler.

Defining jobs in Oracle E-Business Suite

In Oracle E-Business Suite, jobs that are to be scheduled with Tivoli Workload

Scheduler are defined in the same way as other Oracle E-Business Suite jobs (and

can be submitted in Oracle Concurrent Manager). When you are submitting the job

in Oracle Concurrent Manager, specify the scheduling and resubmission

information. When you are submitting the job through Tivoli Workload Scheduler,

Tivoli Workload Scheduler will handle the scheduling and re-submission

information.

To define a job, use the Define Concurrent Program Executables and Define

Concurrent Program forms and fill in the general data information for the job. The

job is now available for scheduling from Tivoli Workload Scheduler (and can also

be submitted in Oracle Concurrent Manager).

Running a single job concurrently

If an Oracle E-Business Suite job is scheduled to run more than once in Tivoli

Workload Scheduler, and Tivoli Workload Scheduler launches it concurrently, the

jobs run normally. However, if the Oracle E-Business Suite user has specified that

the job cannot run concurrently, the second job enters a state of WAIT until the

first job completes.

Defining Oracle E-Business Suite jobs in Tivoli Workload Scheduler

Tivoli Workload Scheduler job definitions are required for each Oracle E-Business

Suite job you plan to schedule. Oracle E-Business Suite jobs are defined in Tivoli

Workload Scheduler like other jobs and include job name, user name, and recovery

options. See Chapter 5, “Defining extended agent jobs,” on page 53.

Task string parameters for Oracle E-Business Suite jobs

This section describes the task string parameters that manage the operation of

Oracle E-Business Suite jobs. Specify them in the following places when you define

their associated Tivoli Workload Scheduler jobs:

v In the Command field of the Task page of the Properties - Job Definition

Window, if you use the Job Scheduling Console.

v As arguments of the scriptname keyword in the job definition statement, if you

use the Tivoli Workload Scheduler command line.

v As arguments of the JOBCMD keyword in the JOBREC statement in the SCRIPTLIB of

Tivoli Workload Scheduler for z/OS, if you are scheduling in an end-to-end

environment. The following is an example of a JOBREC statement:

JOBREC

JOBCMD(’/-user appslogin -job jobspecs’)

JOBUSR(TWS_user_name)

where:

appslogin The name of a valid Oracle Applications user (Apps login).


|||

|||

|

||

jobspecs The attributes of the Oracle Applications job. For details, see

Table 19.

TWS_user_name

The Tivoli Workload Scheduler for z/OS user who runs the

MCMAGENT access method from the end-to-end scheduling

environment.

Table 19 describes the parameters to define Oracle E-Business Suite jobs.

Table 19. Task string parameters for Oracle E-Business Suite jobs

Parameter Description

-user appslogin

The name of a valid Oracle Applications user (Apps

login).

-job jobspecs The attributes of the Oracle Applications job. There

are four job attributes that must be specified in the

following order:

1. The name of the Applications module used to

sign on to Oracle Applications (for example,

FND).

2. A valid responsibility for the Applications

module (for example, ‘Application

Developer’). This parameter must be enclosed in

single quotes.

3. The name of the application that registered the

job (for example, PO).

4. The job name (for example, POXACR). The job

name must be uppercase.

For example:

-job FND ’Application Developer’ PO POXACR

-prn printopts The two printer options for the job. They must be

entered in the following order:

1. The printer name (optional). If omitted, the

default printer specified in the options file is

used.

2. The number of copies.

For example:

-prn ps4 2

tracelvl Specify the trace setting for the job. Possible values

are:

1 Only error messages are written in the

trace file. This is the default.

2 Informational messages and warnings are

also written in the trace file.

3 A most verbose debug output is written in

the trace file.Refer to Chapter 29, “Configuring the tracing

utility,” on page 247 for detailed information.



|||

||||

Table 19. Task string parameters for Oracle E-Business Suite jobs (continued)


[-vn (’value’|null|:parameter)] The job’s parameters, if any. This string is optional

if no parameters are specified for the job in Oracle

Applications.

v n is the parameter number (v1, v2, and so on).

v One of the following:

value An actual value. Enclose value in single

quotes if it contains special characters.

:parameter

The name of an already defined Tivoli

Workload Scheduler parameter. For

more information about Tivoli Workload

Scheduler parameters, refer to the Tivoli

Workload Scheduler Reference Guide.

The access method automatically adds all the

parameters that you do not specify in the

definition with a value of null.

These are two examples:

-v4 ’abc’

-v15 :p1

The following is an example of an entire task string specification:

-user GLOBAL -job FND ’Application Developer’ PO POXACR -prn ps4 2 -v1 ’abc’

Tivoli Workload Scheduler and Oracle E-Business Suite job states

When an Oracle E-Business Suite job is launched by Tivoli Workload Scheduler,

you can monitor its progress with conman. Table 20 provides you with a list of the

state transitions in Tivoli Workload Scheduler and the corresponding Oracle

E-Business Suite states.

Table 20. Tivoli Workload Scheduler and Oracle E-Business Suite job states

Oracle Concurrent Manager States Tivoli Workload Scheduler States

Request Failure or Request not Found UT (unsupported task)

Inactive SUSP

Pending WAIT

Pending Normal ADD

Running Normal EXEC

Completed Normal SUCC

Completed Warning SUCC

Completed Error ABEND

Completed Terminated ABEND

Completed Canceled ABEND

For more information about job management, refer to the Tivoli Workload Scheduler

Reference Manual.


Chapter 8. Defining Oracle E-Business Suite jobs 69






Applications for PeopleSoft

Using Tivoli Workload Scheduler for Applications for PeopleSoft you can run and

monitor PeopleSoft jobs from the Tivoli Workload Scheduler environment. These

jobs can be run as part of a schedule or submitted for ad-hoc job processing.

PeopleSoft extended agent jobs can have all of the same dependencies and

recovery options as other Tivoli Workload Scheduler jobs. PeopleSoft jobs must be

defined in Tivoli Workload Scheduler to be run and managed in the Tivoli

Workload Scheduler environment.




for Applications,” on page 5, you must have the following:

v PeopleTools version 8.44, or later.

v Access to the psjoa.jar file located in the ps_home\class directory.

Features

Using Tivoli Workload Scheduler for Applications for PeopleSoft, you can perform

the following tasks:

v Use Tivoli Workload Scheduler standard job dependencies on PeopleSoft jobs.

v Schedule PeopleSoft jobs to run on specified days, times, and in a prescribed

order.

v Define inter-dependencies between PeopleSoft jobs and Tivoli Workload

Scheduler jobs that run on different applications such as SAP R/3 and Oracle

E-Business Suite.

v Define inter-dependencies between PeopleSoft jobs and jobs that run on different

operating systems.




actors in the process model, showing the tasks they perform.

Table 21. Roles and responsibilities in Tivoli Workload Scheduler for Applications for

PeopleSoft

User role User task






v “Defining Peoplesoft jobs in Tivoli Workload

Scheduler” on page 83

v “Configuring the job status mapping policy” on

page 85


|

|||

|||

||

|||

||||

||


PeopleSoft (continued)

User role User task

PeopleSoft administrator v “Creating a batch processing ID in PeopleSoft” on

page 78

v “Configuring the ITWS_PSXA PeopleSoft project”

on page 78

v “Uploading the PeopleSoft project” on page 79

Scheduling process for the PeopleSoft extended agent

Tivoli Workload Scheduler can launch and monitor jobs in the PeopleSoft process

scheduler using a PeopleSoft extended agent workstation. The PeopleSoft extended

agent is defined in a standard Tivoli Workload Scheduler workstation definition.

This definition is a logical workstation name and specifies the access method as

psagent. The access method is used to communicate job requests to the PeopleSoft

process scheduler.

To launch a PeopleSoft job, Tivoli Workload Scheduler runs the psagent method,

passing it information about the job. An options file provides the method with the

path, the executable, and other information about the PeopleSoft process scheduler

and application server used to launch the job. The extended agent can then access

the PeopleSoft process request table and make an entry in the table to launch the

job. Job progress and status information is written to the job’s standard list file.

There is no need to install Database connectivity on fault-tolerant agents hosting

PeopleSoft extended agents because the method currently uses the PeopleSoft 3-tier

architecture. You must configure at least one PeopleSoft Application Server for the

extended agent to work. The application server must be active to successfully

submit jobs to the PeopleSoft process scheduler.

PeopleSoft job tracking in Tivoli Workload Scheduler

A PeopleSoft job is a collection of processes that run together as a single unit.

Tivoli Workload Scheduler jobs can be defined in one of the following ways:

v As PeopleSoft jobs, that is, as a collection of PeopleSoft processes. In this case,

the status of the PeopleSoft job is tracked, not the status of the individual

processes within the job.

v As PeopleSoft processes. In this case, the status of the individual process is

tracked and Tivoli Workload Scheduler schedules can be defined to create

complex inter-dependencies and recovery options between PeopleSoft processes.

Security

Security for the PeopleSoft jobs is handled by standard Tivoli Workload Scheduler

security.

Features


||

||

|||

||

||

|

Chapter 10. Configuring the PeopleSoft access method

This chapter provides detailed reference information about the PeopleSoft options

and how to define them in the options file. It also describes the tasks for:

v “Creating a batch processing ID in PeopleSoft” on page 78

v “Configuring the ITWS_PSXA PeopleSoft project” on page 78

v “Uploading the PeopleSoft project” on page 79


The Tivoli Workload Scheduler for Applications installation process creates a

default global options file for the psagent access method, named psagent.opts.

You can also create local files, named WORKSTATIONNAME_psagent.ops, which must

be located in the TWShome/methods directory of the hosting computer for the

extended agent.

To edit both options file, you can use either the Option Editor available with this

product, or any other text editor. For details about how to create and edit the

options files with the Option Editor, see Chapter 3, “Setting options with the

Option Editor,” on page 43. For examples of options files for this access method,

see“PeopleSoft options file example” on page 77.

Table 22 describes the options for the psagent access method. Option names are

case insensitive. Before you use a manually-created options file, check that all the

option names are written correctly, otherwise they will be ignored.

Table 22. Psagent access method options

Option Description

CHECKINTERVAL (Optional) Specifies the frequency (in seconds) with which

the psagent monitors a submitted process up to completion.

The default is 120.

LJUSER (Optional) Specifies the ID of the Tivoli Workload Scheduler

user that runs the psagent to launch jobs (LJ tasks). This

user must be a valid Tivoli Workload Scheduler user on the

Tivoli Workload Scheduler hosting workstation.

PS_DISTSTATUS (Optional) Determines whether the distribution status of the

PeopleSoft request is taken into account when determining

the status of the Tivoli Workload Scheduler job. Values are 0

(not taken into account) or 1 (taken into account - the

default value).

PSFT_OPERATOR_ID (Mandatory) Specifies the PeopleSoft operator ID used for

the connection to the PeopleSoft application server.

PSFT_OPERATOR_PWD (Mandatory) Specifies the encrypted password

(case-sensitive) of the PeopleSoft operator ID used for the

connection to the PeopleSoft application server.

For details about how to encrypt the password, see

“Encrypting PeopleSoft operator passwords” on page 77.


Table 22. Psagent access method options (continued)

Option Description

PSJOAPATH (Optional) Specifies the full path name of the psjoa.jar file.

If this option is not set, the path name provided during the

installation is used.

Ensure you identify the version of the psjoa.jar file that

corresponds to the version of PeopleSoft that you are using.

RUNLOCATION (Optional) Specifies the default PeopleTools process server

that processes the requests.

SERVER_NAME_LIST (Mandatory) Specifies the list of application servers that the

psagent tries to connect to. It is a comma-separated list of

addresses in the format:

<server>:<port> [,<server>:<port>] ...

where:

<server> Species the host name or TCP/IP address

of the server

<port> Specifies the port number the server is

listening on.

TWS_MAX_WAIT_TIME (Optional) Specifies the maximum time that the extended

agent waits (timeout) after a failed operation on the

PeopleSoft application server before retrying the operation.

The default is 10 seconds.

TWS_MIN_WAIT_TIME (Optional) Specifies the minimum time that the extended

agent waits (timeout) after a failed operation on the

PeopleSoft application server before retrying the operation.

The default is 5 seconds.

TWS_RETRY (Optional) The maximum number of times that the

extended agent attempts a failed operation on the

PeopleSoft application server. The default is 5.

TWSXA_INLINE_CI (Optional) Specifies the name of the component interface

that the psagent invokes to submit jobs to PeopleSoft.

The default is ITWS_PROCESSREQUEST. If you use this default,

you must perform the customization steps described in

“Configuring the ITWS_PSXA PeopleSoft project” on page

78.

If you do not plan to schedule jobs containing in-line

variables, and you do not want to perform the additional

customization steps, you must replace the default value

with PROCESSREQUEST. This is the component interface

invoked by previous versions of the access method; it does

not allow the use of in-line variables.

TWSA_SCHED_METH (Optional) Specifies the name of the PeopleSoft method

invoked by the component interface specified in

TWSXA_INLINE_CI. Both ITWS_PROCESSREQUEST and

PROCESSREQUEST use the default method Schedule.

If you are using either of these component interfaces, leave

the default. If you are using a different component interface,

specify the name of the method called by your component

interface, respecting the case of the PeopleSoft object name.

Defining PeopleSoft options


PeopleSoft options file example

Below is a sample options file for PeopleTools version 8.44. It can help you

determine your specific site requirements although your options file might be

different.

Remember to save the file in the TWShome\methods directory.

LJuser=TwsUsr

CheckInterval=120

PSFT_OPERATOR_ID=PSHC

PSFT_OPERATOR_PWD=*****

SERVER_NAME_LIST=9.87.120.36:9000

If you create the options file manually, you must encrypt the PeopleSoft operator

password, as described in “Encrypting PeopleSoft operator passwords.”

Encrypting PeopleSoft operator passwords

When you add or change the PeopleSoft operator password using the Option

Editor, the password is automatically encrypted and inserted into the file, and

appears as asterisks on the screen.

When you add or change the PeopleSoft user password using a text editor, you

must run the pwdcrypt program to encrypt the password before writing it in the

file. To run the encryption program, enter the following command:

pwdcrypt password

The program returns an encrypted version that you can then copy and paste into

the options file.






Tivoli Workload Scheduler for Applications version 8.4, so you do not need to

encrypt the password again.

Connecting to more than one PeopleSoft application server

It might be necessary for thepsagent method to connect to more than one

PeopleSoft application server. For example, a single installation of PeopleSoft might

have a TEST, DEMO, and PRODUCTION environment, each with a separate

application server. This requires that the psagent method uses a separate connect

string for each application server.

To support this, you can set up multiple PeopleSoft extended agent workstations

that connect to the same method but use different options files. When a

workstation starts the method, it first looks for the options file with extended agent

workstation name prepended to psagent.opts. For example, a PeopleSoft extended

agent named ps847system would have the following options file:

ps847system_psagent.opts

The psagent method searches first for an options file with the extended agent

workstation name, and then for the default psagent.opts file. This allows the user

to set up an extended agent for each PeopleSoft application server.


Chapter 10. Configuring the PeopleSoft access method 77

|||||||

To connect to only one application server, use the default name for the options file,

psagent.opts.

Creating a batch processing ID in PeopleSoft

Create an operator ID in PeopleSoft dedicated to batch scheduling. This operator

ID must be granted authority to use the Component Interface in the PeopleTools

environment. All the jobs submitted by IBM Tivoli Workload Scheduler should use

this operator ID.

Configuring the ITWS_PSXA PeopleSoft project

The configuration steps described in this section are necessary to enable Tivoli

Workload Scheduler for Applications to schedule PeopleSoft jobs that have in-line

variables in their definitions.

The ITWS_PROCESSREQUEST component interface works around some limitations of

the PeopleSoft APIs when invoked from a batch environment. Because of these

limitations, Tivoli Workload Scheduler cannot schedule jobs defined with in-line

bind variables. With current PeopleSoft APIs, data that is stored in the PeopleSoft

database and referred to by a runcontrol ID parameter that is used to retrieve a

runcontrol data record, needs to be loaded into the Component Buffer before

scheduling the API invocation. This cannot be done from a batch environment.

Therefore, when invoking the PeopleSoft scheduling APIs from a batch interface,

the data related to the runcontrol ID is not available for the submission of a job,

even though it is available in the database. When unresolved data is present in the

submitted job, the PeopleSoft system refuses submission and ends with an error.

The ITWS_PROCESSREQUEST component interface enables Tivoli Workload Scheduler

for Applications to schedule PeopleSoft jobs that have in-line variables in their

definitions. By invoking this component interface, the access method provides the

ability to use data stored in the PeopleSoft database to resolve in-line variable

values by taking data from the database and substituting it with variable

definitions. It then allows job submission regardless of the use of in-line variable

definitions in the jobs. The variable substitution mechanism does not support work

records, so if the PeopleSoft process uses work records in its parameter list, you

find a message similar to the following in the Tivoli Workload Scheduler joblog:

Error Position: 21

Return: 942 - ORA-00942: table or view does not exist

Statement:

select nvsdlist from PS_NVS_WRK WHERE BUSINESS_UNIT = :1 AND REPORT_ID = :2

Original Statement:

SELECT NVSDLIST FROM PS_NVS_WRK WHERE BUSINESS_UNIT = :1 AND REPORT_ID = :2.

To identify work records, use the following PeopleSoft naming conventions:

v A derived work record name ends with ’_WRK’.

v A work record definition name for Structured Query Report reports starts with

R_

When you use Tivoli Workload Scheduler to submit a process that has in-line bind

variables, the name of the process type in the PeopleSoft GUI becomes

ITWS_process type. For example, SQR Process becomes ITWS_SQR Process.

To schedule a job that contains in-line variables in its definition you must perform

the following tasks:



v Leave the value of the TWSXA_INLINE_CI option set to ITWS_PROCESSREQUEST, that

is the default value. See “Defining the configuration options” on page 75 for a

detailed explanation.

v Upload the PeopleSoft project as described in “Uploading the PeopleSoft

project.”

Uploading the PeopleSoft project

This section describes how to upload a new PeopleSoft project related to

PeopleTools 8.44, or later, into the PeopleSoft database. The name of the PeopleSoft

project is ITWS.

After installing the product as described in Chapter 2, “Installing, upgrading, and

uninstalling IBM Tivoli Workload Scheduler for Applications,” on page 5, perform


1. Mount the PT844 PeopleSoft project directory or copy it to the workstation

from where you launch the Application Designer. Tivoli Workload Scheduler

installs the PeopleSoft project directories, as shown in the following structure:

TWS_HOME\methods\

\---PeopleSoft

\---PT844

\---ITWS_PSXA

ITWS_PSXA.ini

ITWS_PSXA.XML

2. Start the Application Designer and from the sign-on window select to start the

Application Designer in tier-two mode by entering the following information:

v Connection Type: database used; for example, Oracle

v Database Name: database instance name

v User ID: PeopleSoft operator name; for example, PS

v Password of user ID 3. Using the Application Designer, select Tools -> Copy Project-> From file...

4. Using the browser, edit the full path to specify the folder where the project

that you want to load is located.

The project is contained in the TWShome/methods/PeopleSoft/PT844

subdirectories.

After you specify the project folder, a list of projects appears in the Project

Name field of the Copy Project From File window.

5. Choose ITWS_PSXA and click Open. If you already configured ITWS_PSXA

(perhaps after installing a fix pack), a confirmation window enquires if you

want to replace the existing one. Click Yes.

The Copy window is displayed showing a list of definition types.

6. Click Options to select the new settings.

a. Click Report Filter

b. Click Select All

c. Click OK

d. Click Select All

e. Click Copy. A progress bar appears

After loading the project, the PeopleSoft Database contains the following

objects:

v ITWS process type definitions

v ITWS permissions list

Configuring ITWS_PSXA PeopleSoft project


v ITWS component interfaces 7. Create the ITWS_ROLE security role. You can use either the PeopleSoft Web GUI

or the Application Designer. Follow the steps below:

From the menu of the PeopleSoft Web GUI:

a. Select: People tools -> Security -> Permission and Roles -> Roles

b. Select the Add a new value tab

c. Type or select ITWS_ROLE in the Role Name field

d. Select the Permissions list tab -> ITWS -> Save

From the Application Designer GUI:

a. Using Maintain Security, edit the ITWS_ROLE window

b. Select the Permissions list tab -> ITWS -> Save

8. Grant ITWS_ROLE authority to all users who want to schedule jobs from Tivoli

Workload Scheduler. You can use either the PeopleSoft Web GUI or the

Application Designer. Follow the steps below:

From the PeopleSoft Web GUI:

a. Select: People tools -> Security -> User Profiles

b. Type the user name of the user who wants to schedule jobs from Tivoli

Workload Scheduler

c. Select the Roles tab

d. Add ITWS_ROLE and save


a. Using Maintain Security, edit the user name

b. Select the Roles tab

c. Add ITWS_ROLE and save 9. Add the ITWS process type definitions to the required PeopleTools process

scheduler. You can use either the PeopleSoft Web GUI or the Application

Designer. Follow the steps below:

From the PeopleSoft Web GUI:

a. Select PeopleTools -> Process Scheduler -> Servers

b. Select your PeopleTools server

c. Add the ITWS_* Type definitions and save


a. Select Process Scheduler Manager

b. Select your PeopleTools server

c. Add the ITWS_* Type definitions and save

Note: From the SQL interactive command line, the same task can be

performed by the following sample statement, customized for your

database environment:

INSERT INTO PS_SERVERCLASS SELECT o.SERVERNAME,

o.OPSYS,’ITWS_’||o.PRCSTYPE,o.PRCSPRIORITY,

o.MAXCONCURRENT FROM PS_SERVERCLASS

o WHERE ( SELECT count(*) FROM PS_SERVERCLASS i WHERE

i.SERVERNAME=o.SERVERNAME AND i.OPSYS=o.OPSYS AND

i.PRCSTYPE=’ITWS_’||o.PRCSTYPE ) = 0

AND ( select count(*) from PS_PRCSTYPEDEFN

a where a.PRCSTYPE=’ITWS_’||o.PRCSTYPE AND a.OPSYS=o.OPSYS ) > 0

10. Restart the process servers.



You do not need to change the existing Tivoli Workload Scheduler job definitions,

except for the scheduling nVision process, where the runcontrol ID must be

specified using the BUSINESS_UNIT.REPORT_ID convention.

The following is an example of a job definition for the scheduling nVision process:

-process ’NVSRUN’ -type nVision-Report -runcontrol AUS01.VARIABLE

where NVSRUN is the process name and AUS01.VARIABLE is the

BUSINESS_UNIT.REPORT_ID.





Chapter 11. Defining PeopleSoft jobs

This chapter provides job definition information for jobs using the extended agent

for PeopleSoft.

Defining Peoplesoft jobs in Tivoli Workload Scheduler

A Tivoli Workload Scheduler job definition is required for every PeopleSoft job you

want to manage. A Tivoli Workload Scheduler job is associated to an already

defined PeopleSoft job and its definition includes:

v The name of the Tivoli Workload Scheduler job that runs the PeopleSoft job

v The name of the extended agent workstation or workstation class where the

Tivoli Workload Scheduler job runs

v The name of the user launching the job

v Recovery options

v The Script file specifications

For more information, refer to Chapter 5, “Defining extended agent jobs,” on page

53.

Task string parameters for PeopleSoft jobs

This section describes the task string parameters that control the operation of

PeopleSoft jobs. You must specify them in the following places when you define


v In the Command field of the Task page of the Properties - Job Definition panel,

if you use the Job Scheduling Console.





environment. In this case the entire string following the JOBCMD keyword must be

enclosed within double quotes.

The following is an example of a JOBREC statement:

JOBREC

JOBCMD("/-process process_name -type ’process_type’ -runcontrol runcontrol_ID")


where:

process_name The process name for the PeopleSoft job.

process_type The process type for the PeopleSoft job. This entry must be

enclosed within single quotes.

runcontrol_ID The runcontrol ID for the PeopleSoft job.

TWS_user_name


psagent access method from the end-to-end scheduling

environment.


||||

|

|||

|

||

|||

||

||||

Table 23 describes the parameters to define PeopleSoft jobs.

Table 23. Task string parameters for PeopleSoft jobs


-process The process name for the PeopleSoft job.

-type The process type for the PeopleSoft job. This entry must be

enclosed within single quotes.

-runcontrol The runcontrol ID for the PeopleSoft job.

-outputdest The destination of the PeopleSoft job output.

-outputtype The output type of the PeopleSoft job. Possible values are:

v Any

v Email

v File

v None

v Printer

v Web

v Window

If you do not specify any value, Tivoli Workload Scheduler uses

the value associated to the PeopleSoft job you are submitting.

Note: Depending on the PeopleSoft configuration, some

combinations of the value of this option with the value of the

outputformat option are not supported. In this case the

PeopleSoft default value is used.

-outputformat The output format of the PeopleSoft job. Valid values are:

None PDF

CSV PS

DOC RPT

Default RTF

HP SPF

HTM TXT

LP WKS

OTHER XLSNote: Depending on the PeopleSoft configuration, some

combinations of the value of this option with the value of the

outputtype option are not supported. In this case the

PeopleSoft default value is used.

-runlocationdescr The PeopleSoft process scheduler responsible for processing the

PeopleSoft job.

-foldername The name of the report folder used for this job. The folder must

have been already created using PeopleSoft Report Manager.

tracelvl Specify the trace setting for the job. Possible values are:

1 Only error messages are written in the trace file. This

is the default.

2 Informational messages and warnings are also written

in the trace file.

3 A most verbose debug output is written in the trace

file.Refer to Chapter 29, “Configuring the tracing utility,” on page

247 for detailed information.

Note: No syntax checking is performed on the output control values (outputdest,

outputtype, outputformat, and foldername). If the values are not recognized,

defaults are used.



The following is an example of a task string specification for a Peoplesoft 8.44 job:

-process XRFWIN -type ’SQR Report’ -runcontrol 1 -runlocationdescr PSNT

Configuring the job status mapping policy

Tivoli Workload Scheduler calculates the status of a Tivoli Workload Scheduler job

based on the PeopleSoft job Run Status and Distribution Status. In PeopleSoft, the

run status monitors the running of the job until it reaches a final status; the

distribution status monitors the status of the output of the job. If the final status of

a PeopleSoft job is neither success nor warning, Tivoli Workload Scheduler ignores

the distribution status and the Tivoli Workload Scheduler job status is ABEND.

If the final status of a PeopleSoft job is success or warning, you can decide whether

to use the distribution status of the PeopleSoft job when determining the status of

the Tivoli Workload Scheduler job by setting the PS_DISTSTATUS option in the

options file:

0 The distribution status is ignored and the Tivoli Workload Scheduler job

status is calculated as shown in Table 25 on page 86.

1 The distribution status is used and the Tivoli Workload Scheduler job

status is calculated as shown in Table 24. This is the default value.

Table 24 shows the relationship between the run status, the distribution status, and

the Tivoli Workload Scheduler job status. The return code associated with the

status is shown in parentheses. Tivoli Workload Scheduler uses this return code to

evaluate the return code condition you specified in the Return Code Mapping

Expression field of the Properties - Job Definition panel. For more details about

this field, see “Task page” on page 56.

Table 24. Relationship between the run status, the distribution status, and the Tivoli

Workload Scheduler job status

PeopleSoft job run status

PeopleSoft job distribution

status

Tivoli Workload Scheduler

job status

v Success (9)

v Warning (17)

v Posted (5)

v None (0)

SUCC

v Success (9)

v Warning (17)

v Not Posted (4)

v Delete (6)

ABEND

v Success (9)

v Warning (17)

v Not Available (1)

v Processing (2)

v Generated (3)

v Posting (7)

EXEC

v Cancel (1)

v Delete (2)

v Error (3)

v Canceled (8)

v No Success (10)

v Blocked (18)

v Restart (19)

Any distribution status ABEND

Table 25 on page 86 shows the relationship between the PeopleSoft run status and

the Tivoli Workload Scheduler job status. The return code associated with the

status is shown in parentheses. Tivoli Workload Scheduler uses this return code to

evaluate the return code condition you specified in the Return Code Mapping

Expression field of the Properties - Job Definition panel. For more details about

this field, see “Task page” on page 56.


Chapter 11. Defining PeopleSoft jobs 85

Table 25. Relationship between the run status and the Tivoli Workload Scheduler job status

PeopleSoft final run status IBM Tivoli Workload Scheduler status

Cancel (1) ABEND

Delete (2) ABEND

Error (3) ABEND

Hold (4) WAIT

Queued (5) WAIT

Initiated (6) INIT

Processing (7) EXEC

Canceled (8) ABEND

Success (9) SUCC

No Success (10) ABEND

Pending (16) EXEC

Warning (17) SUCC

Blocked (18) ABEND

Restart (19) ABEND

Note: If Tivoli Workload Scheduler fails to retrieve the status of the PeopleSoft job,

the Tivoli Workload Scheduler job status is DONE.

Configuring job status mapping






Applications for SAP

Using Tivoli Workload Scheduler for Applications for SAP, you can create,

schedule, and control SAP jobs using the job scheduling features of Tivoli

Workload Scheduler.





v SAP R/3 version 4.6D, 4.7, 6.10, 6.20, 6.30, 6.40, or 7.00.

v The appropriate SAP R/3 Support Package, as shown in Table 26.

Table 26. SAP R/3 support packages

SAP Versions SAP Notes

4.6D 326752, 352606, 357924, 399449, 435111,

453135, 517672, 602683, 604496, 610480,

612564, 758829, 784446, 790615

4.7 unicode/non-unicode 602683, 604496, 610480, 612564, 758829

6.10 unicode/non-unicode 357924, 399449, 435111, 453135, 517672,

602683, 604496, 610480, 612564, 635095,

758829, 784446, 790615


1079601

6.30 unicode/non-unicode 602683, 604496, 612564, 758829


784446, 790615, 1079601

7.00 unicode/non-unicode 862989

Notes:

1. Note 399449 resolves print parameter issues. Notes 357924 and 517672 are

release-independent.

2. Note 758829 resolves job step management problems. See Table 69 on page 257.

3. Notes 602683, 604496, and 612564 are required if you want to use the BC-XBP 2.0

interface.

InfoPackages are supported by Tivoli Workload Scheduler for Applications on SAP

Business Warehouse systems 2.0B, or later.

Process chains are supported on SAP Business Warehouse systems 3.0B, or later.

The Support Package 9 (SAPKW31009) for SAP Business Warehouse Version 3.1 is

required for the extended agent to be able to launch process chains.

Ensure that you have installed the required SAP Business Warehouse Support

Package, as shown in Table 27 on page 90.


|

||

||

||

|

||

|

||

11

Table 27. SAP Business Warehouse support packages

SAP Business Warehouse Versions SAP Notes

3.0B, 3.50 786748, 786749, 795858, 826878, 1059049,

3.10 786748, 786749, 795858, 826878

7.00 826878, 1059049, 1049735, 1100457, 1130034

Server groups are supported by Tivoli Workload Scheduler for Applications on the

following versions of SAP Basis:

v 6.10 with support package 40

v 6.20 with support package 41

v 6.40 with support package 04, and later

For a list of functions and limitations about SAP R/3 server groups, refer to SAP

Notes 612838, 729317, and 786412.

Features

Table 28 shows the tasks you can perform with Tivoli Workload Scheduler for

Applications for SAP either in a distributed or an end-to-end environment.

Table 28. Tivoli Workload Scheduler for Applications for SAP features

Feature

Distributed

environment End-to-end

Using Tivoli Workload Scheduler standard job

dependencies and controls on SAP jobs

U U

Defining jobs, variants, and extended variants using

the Tivoli Workload Scheduler interface

U

Defining jobs and variants dynamically at run time U U

Scheduling SAP jobs to run on specified days and

times, and in a prescribed order

U U

Defining the national language support options U U

Using the SAP Business Warehouse Support

functions

U U

Customizing job execution return codes U U

Using SAP logon groups for load balancing and

fault-tolerance

U U

Using Business Component-eXternal Interface

Background Processing (XBP 2.0) interface support

to:

v Collect

intercepted

jobs

v Track child

jobs

v Keep all job

attributes when

you rerun a job

v Raise events

v Track child

jobs

v Keep all job

attributes when

you rerun a job

v Raise events

Assigning an SAP job to a server group, for batch

processing

U U

Exporting SAP factory calendars and adding their

definitions to the Tivoli Workload Scheduler

database

U



11

11

11

11

||1

1|

|

|

|

||

1

11

11

1111

1111

1111

111

1111

111

1111

111

1111

111

111111111

111111

1111

111

11

Table 28. Tivoli Workload Scheduler for Applications for SAP features (continued)

Feature

Distributed

environment End-to-end

Defining internetwork dependencies and event rules

for Tivoli Workload Scheduler based on SAP events

U

Defining event rules based on IDoc records U

Rerunning a job that submits a process chain from a

specific process, from failed processes, or as a new

instance

U U

Displaying the details of a job that submits a

process chain

U U

Scheduling process for the SAP extended agent

Tivoli Workload Scheduler launches jobs in SAP using jobs defined to run on a

Tivoli Workload Scheduler extended agent workstation. An SAP extended agent

workstation is defined as a Tivoli Workload Scheduler workstation that is hosted

by a fault-tolerant agent or master workstation which uses the r3batch access

method. The SAP extended agent workstation uses the access method r3batch to

pass SAP job-specific information to predefined SAP instances. The access method

uses information provided in an options file, described in Chapter 14, “Configuring

the SAP R/3 access method,” on page 103, to connect and launch jobs on an SAP

instance.

Multiple extended agent workstations can be defined to use the same host, by

using multiple options entries or multiple options files. Using the SAP extended

agent name as a key, r3batch uses the corresponding options file to determine

which instance of SAP will run the job. It makes a copy of a template job in SAP

and marks it as able to run with a start time of start immediate. It then monitors

the job through to completion, writing job progress and status information to a job

standard list on the host workstation.

For more information about job management, refer to the IBM Tivoli Workload

Scheduler Reference Guide.




users in the process model, showing the tasks they perform.

Table 29. Roles and responsibilities in Tivoli Workload Scheduler for Applications for SAP

User role User task


Applications administrator

v “Creating the IBM Tivoli Workload Scheduler RFC

user” on page 95

v “Creating the authorization profile for the Tivoli

Workload Scheduler user” on page 95

v “Copying the correction and transport files” on

page 98

v “Importing ABAP/4 function modules into SAP

R/3” on page 98

Features

Chapter 12. Introducing Tivoli Workload Scheduler for Applications for SAP 91

1

1111

1111

111

111

11

1111

1

1

|

|||

||

||

||||

||

||

||


SAP (continued)

User role User task



v “Changing the Tivoli Workload Scheduler RFC

user ID password” on page 101

v “Migrating from previous versions” on page 101

v “Print parameter and job class issues” on page 102

v “Defining the configuration options” on page 103

v “Connecting to the SAP system” on page 112

v “Defining user authorizations to manage SAP R/3

Business Warehouse InfoPackages and process

chains” on page 164

v Chapter 19, “Using the BDC Wait option,” on page

173

v “Implementing job interception” on page 175

v Chapter 21, “Exporting SAP R/3 factory

calendars,” on page 181

v “Setting National Language support options” on

page 203



v “Defining a job that runs an SAP job” on page 115

v “Editing a standard SAP job” on page 128

v “Task string to define SAP jobs” on page 129

v “Displaying details about a standard SAP job” on

page 141

v “Verifying the status of a standard SAP job” on

page 144

v “Deleting a standard SAP job from the SAP

database” on page 144

v “Balancing SAP workload using server groups” on

page 144

v “Managing SAP R/3 Business Warehouse

InfoPackages and process chains” on page 164

v Chapter 17, “Defining SAP jobs dynamically,” on

page 149

v Chapter 22, “Defining internetwork dependencies

and event rules based on SAP R/3 events,” on

page 185

v Chapter 23, “Defining event rules based on IDoc

records,” on page 195


Applications operator

v “Rerunning an SAP job” on page 137

v “Displaying details about a process chain job” on

page 142

v “Mapping between Tivoli Workload Scheduler and

SAP job states” on page 145

v “Raising an SAP event” on page 145

v “Killing an SAP job instance” on page 147

Scheduling process for the SAP extended agent


||

||

||||

|

|

|

|

|||

||

|

||

||

|||

|

|

||

||

||

||

||

||

|||

11

|||

11

||

|

|||

Unicode support

Tivoli Workload Scheduler for Applications for SAP supports the Unicode

standard.

What is Unicode

Unicode was devised to address the problem caused by the profusion of code sets.

Since the early days of computer programming hundreds of encodings have been

developed, each for small groups of languages and special purposes. As a result,

the interpretation of text, input, sorting, display, and storage depends on the

knowledge of all the different types of character sets and their encodings.

Programs are written to either handle one single encoding at a time and switch

between them, or to convert between external and internal encodings.

The problem is that there is no single, authoritative source of precise definitions of

many of the encodings and their names. Transferring text from one computer to

another often causes some loss of information. Also, if a program has the code and

the data to perform conversion between many subsets of traditional encodings,

then it needs to hold several Megabytes of data.

Unicode provides a single character set that covers the languages of the world, and

a small number of machine-friendly encoding forms and schemes to fit the needs

of existing applications and protocols. It is designed for best interoperability with

both ASCII and ISO-8859-1, the most widely used character sets, to make it easier

for Unicode to be used in applications and protocols.

Unicode makes it possible to access and manipulate characters by unique numbers,

their Unicode code points, and use older encodings only for input and output, if at

all. The most widely used forms of Unicode are:

v UTF-32, with 32-bit code units, each storing a single code point. It is the most

appropriate for encoding single characters.

v UTF-16, with one or two 16-bit code units for each code point. It is the default

encoding for Unicode.

v UTF-8, with one to four 8-bit code units (bytes) for each code point. It is used

mainly as a direct replacement for older MBCS (multiple byte character set)

encodings.

Unicode support on r3batch

Starting with R/3 version 4.7 (R/3 Enterprise), Unicode is used on all layers of the

R/3 system:

v UTF-8, UTF-16, and UTF-32 on the database

v UTF-16 on the application server and graphical user interface

r3batch uses the UTF-8 code page internally. Because it communicates with SAP

R/3 at the application server layer, it uses UTF-16 when communicating with

Unicode-enabled SAP R/3 systems.

To use Unicode support, your system must meet the following conditions:

v Tivoli Workload Scheduler for Applications for SAP version 8.4 must run on one

of the following operating systems:

– Microsoft Windows XP with SP1, 32-bit version

– Microsoft Windows 2000, 32-bit version

– Microsoft Windows 2003, 32-bit version

Unicode support

Chapter 12. Introducing Tivoli Workload Scheduler for Applications for SAP 93

– IBM AIX, 64-bit versions: 5.2, 5.3, 5.4

– Sun Solaris Operating Environment, 64-bit versions 9, 10

– HP-UX, 64-bit versions: 11i v2, 11i v3

– Red Hat Enterprise Linux Advanced Server versions 4.0, 5.0

– SuSE Linux Enterprise Server version 9.0, 10.0

The product does not support Unicode on the other operating systems where it

can be installed.

v The SAP R/3 systems that communicate with r3batch must be running

Unicode-enabled SAP R/3 versions.

v If you are scheduling your jobs through the Job Scheduling Console, use at least

version 1.3. r3batch cannot support Unicode with earlier versions of the Job

Scheduling Console.

If these conditions are not met, you cannot use Unicode support and must make

sure that r3batch, the Job Scheduling Console, and the target SAP R/3 system code

page settings are aligned. Use the options related to national language support

described in “SAP R/3 supported code pages” on page 204.

Unicode support on r3batch


Chapter 13. Configuring the SAP R/3 environment

To communicate and manage the running of jobs on SAP R/3 systems using the

access method for SAP R/3, perform the following configuration steps in the SAP

R/3 environment.

The steps described in this chapter require that you have knowledge of an SAP

R/3 BASIS Administrator.

Overview

Here is an overview of the customization procedure:

1. Create a new user ID for RFC communications in SAP R/3 for Tivoli Workload

Scheduler.

2. Create the authorization profile as described in “Creating the authorization

profile for the Tivoli Workload Scheduler user.”

3. Copy the correction and transport files from the Tivoli Workload Scheduler

server to the SAP R/3 server.

4. Import the correction and transport files into SAP R/3 and verify the

installation.

Note: The import procedure adds new ABAP/4 function modules and several new

internal tables to the SAP R/3 system. It does not modify any of the existing

objects.

Creating the IBM Tivoli Workload Scheduler RFC user

For Tivoli Workload Scheduler to communicate with SAP R/3, you must create a

user ID in SAP R/3 for Tivoli Workload Scheduler batch processing. For security

reasons, use a new user ID rather than an existing one.

1. Create a new RFC user ID.

2. Give this new RFC user ID the following attributes:

v A user type of CPIC, Communications, or DIALOG, depending on the SAP

R/3 release.

v A password at least six characters in length. Tivoli Workload Scheduler

requires this password to start or monitor SAP R/3 jobs. If this password

changes in SAP R/3, you must update the options file used by r3batch with

the new password.

v The appropriate security profiles, depending on your version of SAP R/3.

Creating the authorization profile for the Tivoli Workload Scheduler

user

There are two alternative ways to perform this task:

v Using transaction SU02 and manually creating the profile.

v Using the Profile Generator (transaction PFCG).


Using Transaction SU02 and manually creating the profile

Perform the following steps:

1. Write a profile name, for example Z_TWS, and a description.

2. Manually add the authorizations according to the following table:

Object Description Authorization

S_ADMI_FCD System authorizations S_ADMI_ALL

S_BTCH_ADM Background processing:

Background administrator

S_BTCH_ADM

S_BTCH_JOB Background processing:

Operations on background

jobs

S_BTCH_ALL

S_BTCH_NAM Background processing:

Background user name

S_BTCH_ALL

S_DEVELOP ABAP Workbench: full

authorization to modify

objects of type PROG

E_ABAP_ALL

S_PROGRAM ABAP: program run checks S_ABAP_ALL

S_RFC Authoritation. check for

RFC access

S_RFC_ALL

S_RZL_ADM CCMS: System

Administration

S_RZL_ALL

S_SPO_ACT Spool: Actions S_SPO_ALL

S_SPO_DEV Spool: Device

authorizations

S_SPO_DEV_AL

S_XMI_LOG Internal access

authorizations for XMI log

S_XMILOG_ADM

S_XMI_PROD Authorization for external

management interfaces

(XMI)

S_XMI_ADMIN

The authorizations are located in the ″Basis: Administration″ object class.

Depending on the version of SAP R/3, the authorization S_RFC_ALL might be

located in the ″Cross-application Authorization objects″ or in the

″Non-application-specific Authorization Objects″ object class.

3. Save the profile.

4. Go to the user maintenance panel and assign the profile to the Tivoli Workload

Scheduler SAP R/3 user.

5. Save the user data.

Using Transaction PFCG (Profile Generator)


1. Write a name, for example ZTWS, in Role Name.

2. Click Create Role and write a description for the role, such as ″Role for the

TWS user″.

3. Save the role.

4. Select Authorizations.

5. Click Change Authorization Data.

Using transaction SU02 and manually creating the profile


1111

1

6. In the pop-up, select Templates.

7. Manually add the following authorization objects:

Object Description

S_ADMI_FCD System authorizations

S_BTCH_ADM Background processing: Background administrator

S_BTCH_JOB Background processing: Operations on background

jobs

S_BTCH_NAM Background processing: Background user name

S_PROGRAM ABAP: Program run checks

S_DEVELOP ABAP Workbench: full authorization to modify

objects of type PROG

S_RFC Authorization check for RFC access

S_RZL_ADM CCMS: System Administration

S_SPO_ACT Spool: Actions

S_SPO_DEV Spool: Device authorizations

S_XMI_LOG Internal access authorizations for XMI log

S_XMI_PROD Authorization for external management interfaces

(XMI)

8. Fill in the values according to the following scheme:

Object Description

S_ADMI_FCD System authorizations

v System administration function: Full

authorization

S_BTCH_ADM Background processing: Background administrator

v Background administrator ID: Full authorization

S_BTCH_JOB Background processing: Operations on background

jobs

v Job operations: Full authorization

v Summary of jobs for a group: Full authorization

S_BTCH_NAM Background processing: Background user name

v Background user name for authorization check:

Full authorization

S_PROGRAM ABAP: Program run checks

v User action ABAP/4 program: Full authorization

v Authorization group ABAP/4 program: Full

authorization

S_RFC Authorization check for RFC access

v Activity: Full authorization

v Name of RFC to be protected: Full authorization

v Type of RFC object to be protected: Full

authorization

S_RZL_ADM Activity: Full authorization


Chapter 13. Configuring the SAP R/3 environment 97

111

Object Description

S_SPO_ACT Spool: Actions

v Authorization field for spool actions: Full

authorization

v Value for authorization check: Full authorization

S_SPO_DEV Spool: Device authorizations

v Spool - Long device names: Full authorization

S_XMI_LOG Internal access authorizations for XMI log

v Access method for XMI log: Full authorization

S_XMI_PROD Authorization for external management interfaces

(XMI)

v XMI logging - Company name: TIVOLI*

v XMI logging - Program name: MAESTRO*

v Interface ID: Full authorization

9. Save the authorizations.

10. Generate a profile. Use the same name that you wrote in Role Name.

11. Exit the authorization management panel and select User.

12. Add the Tivoli Workload Scheduler user to the role.

13. Save the role.

Copying the correction and transport files

The setup file loads four correction and transport files into the Tivoli Workload

Scheduler home directory. Copy these correction and transport files to the SAP R/3

server and import them into the SAP R/3 database, as follows:

1. On your SAP R/3 database server, log onto your SAP R/3 system as an

administrator.

2. Copy the control file and data file from the TWShome\methods directory to the

following directories on your SAP R/3 database server:

copy controlfile /usr/sap/trans/cofiles/

copy datafile /usr/sap/trans/data/

The names of controlfile and datafile vary from release to release. The files are

installed in the TWShome\methods directory and have the following file names

and format:

For SAP R/3 releases earlier than 6.10:

v K000xxx.TV1 (control file) and R000xxx.TV1 (data file)

v K900xxx.TV2 (control file) and R900xxx.TV2 (data file)

For SAP R/3 release 6.10, or later:

v K9005xx.TV1 (control file) and R9005xx.TV1 (data file)

v K9006xx.TV1 (control file) and R9006xx.TV1 (data file)

where x is a digit generated by the SAP system.

Importing ABAP/4 function modules into SAP R/3

This section describes the procedure to generate, activate, and commit new

ABAP/4 function modules to your SAP R/3 system and several new internal

tables. You do not modify any existing SAP R/3 system objects.



1

11

The number of ABAP/4 modules that you install with the import process varies

from release to release. The modules are installed in the TWShome\methods directory

and have the following file names and format:

For SAP R/3 releases earlier than 6.10:

v K000xxx.TV1 (function modules for standard job scheduling extensions)

v K900xxx.TV2 (function modules for IDoc monitoring)

For SAP R/3 release 6.10, or later:

v K9005xx.TV1 (function modules for standard job scheduling extensions)

v K9006xx.TV1 (function modules for IDoc monitoring)

where x is a digit generated by the SAP system.

To import ABAP/4 function modules into SAP R/3:

1. Change to the following directory:

cd /usr/sap/trans/bin

2. Add the transport file to the buffer:

tp addtobuffer transport sid

where:

transport The transport request file.

sid The SAP R/3 system ID.

For example, if the transport file in the TWShome\methods directory is named

K900xxx.TV1, the transport request is tv1K900xxx.

3. Run the tp tst command to test the import:

tp tst transport sid

After running this command, examine the log files in the /user/sap/trans/log

directory for error messages. Warnings of severity level 4 are normal.

If there are errors, check with a person experienced in correction and transport,

or try using unconditional modes to do the import.

4. Run the following command to import all the files in the buffer:

tp import transport sid

This command generates the new ABAP/4 modules and commits them to the

SAP R/3 database. They automatically become active.

After running this command, examine the log files in the /user/sap/trans/log

directory for error messages. Warnings of severity level 4 are normal.

If a problem is encountered, use unconditional mode when running this step:

tp import transport sid U126

5. When the import is complete, check the log files stored in the

/usr/sap/trans/log directory to verify that the ABAP/4 modules were

imported successfully.

The number of ABAP/4 modules installed by the import process varies

depending on the SAP release you are using. If you are using an SAP release

earlier than 6.10, 42 modules are installed. If you are using SAP release 6.10 or

later and you apply the standard transport and the IDOC transport, 20 modules

are installed. For a list of the transport files to be used, refer to “Importing

ABAP/4 function modules into SAP R/3” on page 98. Table 30 on page 100

lists the ABAP modules installed according to the SAP release.

Importing ABAP/4 modules into SAP R/3


111

111

111

1

1111

Table 30. ABAP/4 modules

ABAP/4 module

SAP releases earlier

than 6.10

SAP releases 6.10 or

later

J_1O1_BDC_STATUS U U

J_1O1_DATE_TIME U U

J_1O1_IDOC_SELECT U U

J_1O1_JOB_ADJUST_CLIENT U U

J_1O1_JOB_ABAP_STEP_MODIFY U

J_1O1_JOB_ADD_ABAP_STEP U

J_1O1_JOB_ADD_EXTPGM_STEP U

J_1O1_JOB_CLOSE U

J_1O1_JOB_COPY U

J_1O1_JOB_DEFINITION_GET U

J_1O1_JOB_DELETE U

J_1O1_JOB_EXTPGM_STEP_MODFY U

J_1O1_JOB_FIND U U

J_1O1_JOB_FINDALL U U

J_1O1_JOB_HAS_EXTENDED_VARIANT U U

J_1O1_JOB_LOG U U

J_1O1_JOB_LOG_READ U

J_1O1_JOB_OPEN U

J_1O1_JOB_START U

J_1O1_JOB_STATUS U

J_1O1_JOB_STATUS_CHECK U

J_1O1_JOB_STOP U

J_1O1_RAISE_EVENT U U

J_1O1_REPORT_ALL_SELECTIONS U U

J_1O1_REPORT_DYNSEL_GET_DEF U

J_1O1_REPORT_GET_TEXTPOOL U U

J_1O1_TABLE_GET_NAMETAB U

J_1O1_VARIANT_COPY U U

J_1O1_VARIANT_COPY_4X U

J_1O1_VARIANT_CREATE U U

J_1O1_VARIANT_CREATE_NEW U

J_1O1_VARIANT_DELETE U U

J_1O1_VARIANT_DELETE_NEW U

J_1O1_VARIANT_EXISTS U U

J_1O1_VARIANT_GET_DEFINITION U U

J_1O1_VARIANT_GET_DEF_NEW U

J_1O1_VARIANT_GET_HELP_VALUES U U

J_1O1_VARIANT_INFO_GET U

J_1O1_VARIANT_MAINTAIN_CNT_TBL U U



111

Table 30. ABAP/4 modules (continued)

ABAP/4 module

SAP releases earlier

than 6.10

SAP releases 6.10 or

later

J_1O1_VARIANT_MAINTAIN_SEL_TBL U U

J_1O1_VARIANT_MODIFY U U

J_1O1_VARIANT_MODIFY_NEW U

Changing the Tivoli Workload Scheduler RFC user ID password

If the password of the Tivoli Workload Scheduler RFC user ID is modified after the

initial installation, the options file used by r3batch must be updated with this

change.

In UNIX, log on as root to the system where Tivoli Workload Scheduler is

installed.

In Windows, log on as an administrator and start a DOS shell on the system where

Tivoli Workload Scheduler is installed, as follows:

1. Generate an encrypted version of the new password using the enigma

command in TWShome/methods. To do this in a command shell, type:

enigma newpwd

where newpwd is the new password for the Tivoli Workload Scheduler RFC

user ID.

The enigma command prints an encrypted version of the password.

2. Copy the encrypted password into the options file, which is located in the

TWShome/methods directory. The file can be edited with any text editor.

Ensure you copy the password exactly, preserving uppercase, lowercase, and

punctuation. The encrypted password looks similar to:

{3des}Hchwu6IsF5o=

If the encrypted password is not entered correctly, Tivoli Workload Scheduler is

unable to start or monitor SAP R/3 batch jobs.

Migrating from previous versions

This version of the Tivoli Workload Scheduler extended agent for SAP R/3

supports all the SAP R/3 versions listed in Table 26 on page 89. The Tivoli

Workload Scheduler extended agent for SAP R/3 version 4.x uses the official SAP

R/3 RFC interfaces for job scheduling. These are:

v The SXMI_XBP interface for SAP R/3 versions 3.1g to 4.0x

v The BAPI_XBP interface since version 4.5a

To avoid conflicts with other vendors, the Tivoli Workload Scheduler ABAP

modules now belong to the Tivoli Workload Scheduler partner namespace

J_1O1_xxx. After you have completed the imports as described in “Importing

ABAP/4 function modules into SAP R/3” on page 98, the RFC J_1O1_xxx function

modules are installed on your system.

If you had a previous installation of Tivoli Workload Scheduler extended agent for

SAP R/3 on your system, you can delete the following function modules from

your SAP R/3 system:



Z_MAE2_BDC_STATUS

Z_MAE2_DATE_TIME

Z_MAE2_JOB_COPY

Z_MAE2_JOB_DELETE

Z_MAE2_JOB_FIND

Z_MAE2_JOB_FINDALL

Z_MAE2_JOB_LOG

Z_MAE2_JOB_OPEN

Z_MAE2_JOB_START

Z_MAE2_JOB_STATUS

Z_MAE2_JOB_STOP

These are old versions of the Tivoli ABAP functions, which belong to the customer

name space. You can also delete the function group YMA3. It is not necessary to

delete the function modules and the function group, but delete them if you want

to clean up your system.

Print parameter and job class issues

The extended agent for SAP R/3 uses the official RFC interfaces of SAP R/3

versions 4.x to 6.40 for job scheduling. When you migrate from previous versions

of SAP R/3, there can be problems with print parameters in jobs launched by

Tivoli Workload Scheduler. This is because of limitations in the RFC interfaces.

These limitations are no longer true with XBP 2.0.

The following is a list of print parameters supported by BAPI XBP 1.0 for SAP R/3

release 4.6x and later:

v output device

v print immediately

v delete after output

v number of copies

v archiving mode

v authorization

v selection cover page

v sap cover page

v spool retention period

v recipient

v lines

v columns

To resolve the loss of print parameters when copying a job, install the appropriate

SAP R/3 Support Package as stated in the SAP R/3 notes 399449 and 430087.

The same applies to the job class. Official SAP R/3 interfaces only allow class C

jobs. Installing the SAP R/3 Support Package also resolves this issue.

Migrating from previous versions


Chapter 14. Configuring the SAP R/3 access method

This chapter provides detailed reference information about the Tivoli Workload

Scheduler for Applications for SAP options and how to define them in the option

files. The options files for the SAP access method are the following:

r3batch.opts

A common configuration file for the r3batch access method, whose settings

affect all the r3batch instances. It functions as a “global” configuration file.

WKSTNAME_r3batch.opts

A configuration file that is specific to each Tivoli Workload Scheduler

extended agent workstation that uses the r3batch access method. Its

options affect only the r3batch instance that is used by that particular

workstation. It functions as a “local” configuration file.

Note: WKSTNAME is the name of the extended agent workstation and must

be written in uppercase characters.

For example, to define two extended agents named wkst1 and wkst2 that access

two SAP systems, SAP1 and SAP2, with the r3batch access method, you must define

the following three configuration files:

v Global r3batch.opts

v Local file WKST1_r3batch.opts

v Local file WKST2_r3batch.opts

Note: If r3batch finds the local configuration file for an extended agent, it ignores

the duplicate information contained in r3batch.opts.


This section describes the options you can configure in r3batch.opts and in

WKSTNAME_r3batch.opts.

Defining the global options

Table 31 lists the options that can be specified only in the global configuration file

r3batch.opts.

Table 31. r3batch global configuration options

Option Description Default

dep_sem_proj (Optional) The project ID for the external dependency

semaphore used for handling SAP R/3 background

processing events as external follows dependencies.

d

icp_sem_proj (Optional) The project ID for the job interception

semaphore.

c

job_sem_proj (Optional) The project ID for the job semaphore. a

primm_enable (Optional) Enables (ON) the SAP print parameter

PRIMM (Print Immediately) for all jobs.

OFF

prnew_enable (Optional) Enables (ON) the SAP print parameter

PRNEW (New Spool Request) for all jobs.

OFF


||

||||

|

||||

||||

Table 31. r3batch global configuration options (continued)


prrel_enable (Optional) Enables (ON) the SAP print parameter

PRREL (Immediately delete the spool output after

printing) for all jobs.

OFF

prsap_enable (Optional) Enables (ON) the SAP print parameter

PRSAP (Print SAP Cover Page) for all jobs. The

default value is OFF.

OFF

prunx_enable (Optional) Enables (ON) the SAP print parameter

PRUNX (Print Operating System Cover Page) for all

jobs.

OFF

var_sem_proj (Optional) The project ID for the variant semaphore. b

Modifying the default values of the semaphore options is particularly useful when

the IDs that are generated would be the same as the IDs already used by other

applications.

On UNIX and Linux, to resolve the problem of duplicated IDs, Tivoli Workload

Scheduler for Applications for SAP uses system-5 semaphores to synchronize

critical ABAP function module calls. It uses one semaphore for job-related tasks

and another one for tasks related to variant maintenance.

To synchronize on the same semaphore, the communication partners must use the

same identifier. There are several ways to choose this identifier. Tivoli Workload

Scheduler for Applications for SAP uses two parameters: a path name and a

project ID (which is a character value). The path name parameter is the fully

qualified path to the options file. The project ID is taken from the options

described in Table 31 on page 103. If these options are omitted, Tivoli Workload

Scheduler for Applications for SAP uses default values, which work for most

installations.

Notes:

1. The semaphore options must be edited directly in the global options file using

a text editor; you cannot use the options editor to modify these values.

2. If two semaphore options are assigned the same value, all the semaphore

values are reset according to the following rule:

job_sem_proj

It keeps the value assigned, or its default value.

var_sem_proj

It is reset to the first character that, in the ASCII table, follows the value

assigned to var_sem_proj.

icp_sem_proj

It is reset to the second character that, in the ASCII table, follows the value


dep_sem_proj

It is reset to the third character that, in the ASCII table, follows the value


SAP global options


||||

|

||||

|

||||

|

|||

||||

||

||

|||

|||

|||

Defining the local options

Table 32 lists the options that you can specify only in the local configuration files.

Table 32. r3batch local configuration options

Option Description

job_duration (Optional) Enables (ON) that the CPU time value in the production

plan report that is run from the Tivoli Dynamic Workload Console

is set to the actual duration of the SAP job. Default value is OFF.

To retrieve the job duration from the SAP system, ensure that the

authorization profile contains the following authorization objects:

v S_DEVELOP

v S_TCODE with parameter SE38 (only for SAP 6.40 and 7.00)

For details about the authorization profile, see “Creating the

authorization profile for the Tivoli Workload Scheduler user” on

page 95.

primm_enable (Optional) Enables (ON) the SAP print parameter PRIMM (Print

Immediately) for all jobs. The default value is OFF.

prnew_enable (Optional) Enables (ON) the SAP print parameter PRNEW (New

Spool Request) for all jobs. The default value is OFF.

prrel_enable (Optional) Enables (ON) the SAP print parameter PRREL (Print

Release) for all jobs. The default value is OFF.

prsap_enable (Optional) Enables (ON) the SAP print parameter PRSAP (Print

SAP Cover Page) for all jobs. The default value is OFF.

prunx_enable (Optional) Enables (ON) the SAP print parameter PRUNX (Print

Operating System Cover Page) for all jobs. The default value is

OFF.

r3client (Mandatory) The SAP client number.

r3gateway (Optional) The host name of the SAP gateway.

r3group (Optional) The name of the SAP logon group.

r3gwservice (Optional) The service number of the SAP gateway.

r3host (Mandatory) The host name of the SAP message server when

using logon groups, or the host name of the application server in

all other cases.

If this server can be reached through one or more SAP gateways,

use a string in the format /H/gateway/H/ for each of them.

r3instance (Mandatory) The SAP instance number.

If r3group is set, this option is ignored.

r3password (Mandatory) The password for the r3user. Ensure you enter the

same password when creating this user in the SAP system. It can

be a maximum of eight characters and is stored in encrypted

format. The value is case sensitive.

For information about how to encrypt the password see

“Encrypting SAP R/3 user passwords” on page 111.

r3sid (Mandatory) The SAP system ID.

r3user (Mandatory) The name of the SAP user with which the access

method connects to the SAP system. It must have the appropriate

privileges for running background jobs. It is sometimes also called

the Maestro™ User ID.

SAP local options

Chapter 14. Configuring the SAP R/3 access method 105

||||

||||

|||

|||

|||

|||

|||

||||

|

Defining the common options

Table 33 lists additional options that you can specify in either configuration file.

Table 33. r3batch common configuration options


bdc_job_status_failed (Optional) How Tivoli Workload Scheduler sets the completion

status of a job running BDC sessions, according to a possible BDC

processing failure. The allowed values are:

n If at least n BDC sessions failed (where n is an integer

greater than 0), Tivoli Workload Scheduler sets the job

completion status as failed.

all If all the BDC sessions failed, Tivoli Workload Scheduler

sets the job completion status as failed.

ignore When all the BDC sessions complete, regardless of their

status, Tivoli Workload Scheduler sets the job completion

status as successful. This is the default.Note: This option is ignored if you defined the job by setting the

nobdc or nobdcwait option. For details about these options, see

“Task string to define SAP jobs” on page 129.

ignore

commit_dependency (Optional) Enables (ON) or disables (OFF) the product to commit

internetwork dependencies after processing.

If you enable this option, internetwork dependencies are

committed immediately by default. If you disable or delete this

option, the -commit parameter set in the internetwork dependency

definition is applied. For details about the -commit parameter, see


OFF

evmon_interval (Optional) The polling rate (in seconds) that the r3evmon process

applies to monitor the list of events.

60

ifuser (Optional) The ID of the user who runs the access method to

retrieve job information.

None

idoc_no_history (Optional) Enables (ON) or disables (OFF) the product to retrieve

only IDoc data that is generated from the time when the

monitoring process has started. If you specify OFF, all matching

IDocs are retrieved, included those that were generated before the

monitoring process started.

When processing this option, r3evmon uses the

XAname_r3idocmon.cfg file to retrieve the date and time for the

next monitoring loop.

ON

idoc_shallow_result (Optional) Enables (ON) or disables (OFF) the product to retrieve

only the most recent matching IDocs.

For example, suppose you set idoc_shallow_result=ON. If the

status of an IDoc changes several times during the monitoring

interval and the same status, matching an event rule condition,

occurs more than once in the sequence of statuses, then only the

most recent matching IDoc is retrieved. If you specify OFF, all

matching IDocs are retrieved.

ON

jobdef (Optional) If enabled, you can use the Job Scheduling Console to

define jobs, in addition to the command line. Specify r3batch to

enable the option, and any other value to disable it.

r3batch

ljuser (Optional) The ID of the user who runs the access method to

launch jobs (LJ tasks) and manage jobs (MJ tasks).

None

SAP common options


111111111111111111

1

|||

|||||

|

||||

111111

111

1

111

111111

1

Table 33. r3batch common configuration options (continued)


log_r3syslog (Optional) Enables (ON) or disables (OFF) the access method to write

the latest entries from the SAP syslog to its trace file when an RFC

returns with a general error.

OFF

long_interval (Optional) The maximum interval, in seconds, between status

checks. It cannot be greater than 3600 seconds. See also

short_interval.

3600

max_n0_counter (Optional) The maximum value of the N0 counter. If the N0

counter reaches the specified value, it starts again from 0.

2^15 - 1

max_name_counter (Optional) The maximum value of the variant name counter. If the

name counter reaches the specified value, it starts again from 0.

40

n0_counter_policy (Optional) The N0 counter policy:

step The N0 counter is increased once for every step.

job The N0 counter is increased once for every job.

job

name_counter_policy (Optional) The name counter policy:

step The name counter is increased once for every step.

job The name counter is increased once for every job.

job

nojobdefs (Optional) Disables (1) or enables (0) the definition of new SAP

jobs using the Job Scheduling Console GUI. If this option is set to

1, you must create the job definitions in the SAP job before

creating the Tivoli Workload Scheduler for Applications job that is

going to schedule them.

0

oldcopy (Optional) Enables (1) or disables (0) the access method to use the

old way of copying jobs, even though the function module

BAPI_XBP_JOB_COPY is present on the SAP system.

0

pchain_recover (Optional) The action taken by Tivoli Workload Scheduler when

you rerun a job that submits a process chain. The allowed values

are:

rerun Tivoli Workload Scheduler creates another process chain

instance and submits it to be run again.

restart Tivoli Workload Scheduler restarts the original process

chain from the failing processes to the end.

For details about rerunning a process chain job, refer to

“Rerunning a process chain job” on page 138.

rerun

pchain_details (Optional) Enables (ON) or disables (OFF) the display of details

about an SAP process chain that you scheduled as a Tivoli

Workload Scheduler job.

OFF

pchainlog_bapi_msg (Optional) Enables (ON) or disables (OFF) the product to retrieve

additional messages from the BAPI calls from the SAP Business

Warehouse process chains and appends them to the stdlist of Tivoli

Workload Scheduler.

ON

SAP common options


1111111111

11

1

1111

1



pchainlog_level (Optional) Supplements the option retrieve_pchainlog.

Specifies which level of process chain logs you want to retrieve.

Permitted values are:

1 Only the first level of process chain is logged.

level_number

Process chains are logged down to the level of chain you

indicate here. For example, if you indicate 2 only the first

two levels are logged.

all All process chains are logged.

If you omit this

option, and leave

retrieve_pchainlog set

to ON, the default is

level 1.

pchainlog_verbosity (Optional) Supplements the option retrieve_pchainlog.

Specifies which type of process chain logs you want to retrieve.

Permitted values are:

chains_only

Logs only the process chains.

chains_and_failed_proc

In addition to the process chains, logs all failed processes.

complete

Logs all process chains and processes.Note: This option affects the entire process chain; verbosity cannot

be reduced for individual processes.

If you omit this

option, and leave

retrieve_pchainlog set

to ON, the default is

complete.

pc_launch_child (Optional) Enables (ON) or disables (OFF) the product to launch

child jobs that are in scheduled state.

Note: You can use this option only if you activated the

parent-child feature on the SAP system. On the XBP 2.0 SAP

system, you can activate this feature by using the INITXBP2 ABAP

report.

OFF

placeholder_abap_step (Optional) If XBP version 2.0 is used, the name of the ABAP report

used as the dummy step in the SAP placeholder job that is created

to monitor an SAP event defined as external dependency.

If this option is not

specified, neither as

global nor local

option, the default

BTCTEST is used.

qos_disable (Optional) Enables (ON) or disables (OFF) the creation of the

environment variable QOS_DISABLE on Microsoft Windows

systems that use the Quality of Service (QoS) feature, before

r3batch opens an RFC connection.

Without this option, because of problems in the implementation of

the QoS service, the connection between r3batch and the SAP RFC

library does not work.

OFF

r3auditlevel (Optional) The audit level for the XBP. A number from 0 (low) to 3

(high).

3

rcmap (Optional) Enables (ON) or disables (OFF) the Return Code mapping

capabilities of Tivoli Workload Scheduler for Applications for SAP.

ON

SAP common options


||||

|||||



retrieve_joblog (Optional) Enables (ON) or disables (OFF) the retrieval and

appending of the SAP job logs to the stdlist of Tivoli Workload

Scheduler.

Notes:

1. The retrieval and appending of job logs to the stdlist might

be time-consuming for jobs that produce large logs.

2. If you disable the retrieval of the job logs, you also disable the

return code mapping function for the log entries.

3. This option does not affect the BDC Wait feature.

ON

retrieve_ipaklog (Optional) Enables (ON) or disables (OFF) the retrieval and

appending of the SAP BW InfoPackage logs to the stdlist of


Note: The retrieval and appending of SAP BW InfoPackage job

logs to the stdlist might be time-consuming for jobs that produce

large logs.

ON

retrieve_pchainlog (Optional) Enables (ON) or disables (OFF) the retrieval and

appending of the SAP BW process chain logs to the stdlist of


Notes:

1. The retrieval and appending of SAP BW process chain logs to

the stdlist might be time-consuming for jobs that produce

large logs.

2. If you disable the retrieval of the SAP BW process chain logs,

you also disable the return code mapping function for the log

entries.

3. This option on its own retrieves the log of only the first level of

a process chain. To retrieve more complete logs, use this option

with the pchainlog_level and pchainlog_verbosity options.

ON

retrieve_spoollist (Optional) Enables (ON) or disables (OFF) the retrieval and

appending of the SAP job spool lists to the stdlist of Tivoli

Workload Scheduler.

Notes:

1. The retrieval and appending of SAP job spool lists to the

stdlist might be time-consuming for jobs that produce large

spool lists.

2. If you disable the retrieval of the SAP job spool lists, you also

disable the return code mapping function for the spool list

entries.

ON

retry (Optional) The retry count for SAP function module calls. Specify

an integer greater than 0.

5

rfc_open_delay (Optional) The maximum number of seconds to wait between two

consecutive calls before opening an RFC connection.

1800

rfc_open_retry (Optional) The retry count for opening an RFC connection to the

SAP system. Specify an integer greater than 0 to limit the number

of retries, or -1 for an unlimited number of retries.

5

rfc_timeout (Optional) The time (in seconds) that r3batch waits before

cancelling a non-responding RFC communication. Allowed values

are in the range from 0 to 9999; 0 means no timeout.

600

short_interval (Optional) The minimum interval, in seconds, between status

checks. It cannot be less than 10 seconds. See also long_interval.

10

SAP common options


1111

1



twsmeth_cp (Optional) The code page that r3batch uses to write its output.

This option must be consistent with twsmeth_lang. It can be any

of the existing TIS codepages.

The code page used

by the Tivoli

Workload Scheduler

workstation that hosts

the r3batch access

method.

twsmeth_lang (Optional) The language used to report messages.

This option must be consistent with twsmeth_cp.

The language of the

locale of the

workstation that hosts

the r3batch access

method.

twsxa_cp (Optional) The encoding used by r3batch to establish RFC

connections with SAP systems.

Use this option if r3batch is not Unicode-enabled. Possible values

are:

v 1100

v 1103

v 8000

v 8300

v 8400

1100

twsxa_lang (Optional) The language used to log in to SAP systems. Specify

one of the following:

DE German

EN English

ES Spanish

FR French

IT Italian

JA Japanese

KO Korean


zh_CN Simplified Chinese

zh_TW Traditional Chinese

DE, EN, and JA can be set from the Option Editor. The other

languages can be set using any text editor.

EN

utf8cmdline (Optional) Enables (1) or disables (0) the encoding of extended

parameters in UTF-8 format. The default value is 0.

Note: If you have

both global and local

options files and you

want to change the

default value for

utf8cmdline, modify

the local options file

because this overrides

the global options.

xbpversion (Optional) The XBP version used on the target SAP system. Specify

an integer value. This value overwrites the XBP version

automatically determined during RFC logon.

Note: For details about XBP 3.0 and SAP Netweaver 2004s with

SP9, refer to the SAP Note 977462.

The XBP version

determined by

r3batch during RFC

logon from the SAP

system.

SAP common options


|||

|||||||

|

||||||||||||

||||||

|||||

SAP R/3 option file example

Below is an example of an options file for SAP. It can help you determine your

specific site requirements, although your options file might be different.

r3client=100

r3host=/H/amsaix64.tivlab.raleigh.ibm.com

r3instance=00

r3password={3des}Hchwu6IsF5o=

r3sid=GS7

r3user=twstest

long_interval=120

r3auditlevel=3

short_interval=10

twsxa_lang=EN

Encrypting SAP R/3 user passwords

When you add your entries in the options file, the password value is automatically

encrypted before it is written in the file. If you modify the file with a text editor,

you must run the enigma program to encrypt the password before writing it in the

file. To run the encryption program, enter the following command:

enigma [password]

You can include the password on the command line or enter it in response to a

prompt. The program returns an encrypted version that you can then enter in the

options file.






Tivoli Workload Scheduler for Applications 8.4, so you do not need to encrypt the

password again.

Configuration options usage

The format of the CPUname_r3batch.opts configuration file is the following:

option1=value1

option2=value2

option3=value3

...

with no blanks before the option, after the value, or before or after the equals (=)

character.

You can put all the common information, such as the LJuser, IFuser, JobDef, and

LogFileName options in r3batch.opts, while you can put tailored data for the target

SAP system of the extended agent (for example, SAP1) in a local configuration file

(for example, wkst1_r3batch.opts).

You can put a local option in the global configuration file if you need to give the

same option to all the r3batch instances. For example, if the SAP user name is the

same in all your SAP systems, you can place the r3user option in the global file

without duplicating that information in all the local configuration files.

A global option, like job_sem_proj, only has effect in the global configuration file.

If you put global options in a local file they have no effect.

SAP common options


|||||||

r3batch reads the global configuration file first and then the local file. Every option

(except the global options) contained in the local configuration file will override

those in the global file. For example, if both the global and the local configuration

files contain the r3user option, r3batch uses the one in the local file.

There are six mandatory options that r3batch requires:

v r3client

v r3host

v r3instance

v r3password

v r3sid

v r3user

You can put them all in the local configuration file or you can spread them

between the global and the local files. For example, you could place r3user and

r3password in the global configuration file and r3sid, r3instance, r3client, and

r3host in the local one.

The r3user option is both local and mandatory. It must be placed either in the

global configuration file or the local configuration file.

Note: These configuration files are not created during the installation process.

Connecting to the SAP system

Tivoli Workload Scheduler for Applications for SAP uses the SAP remote

connection call (RFC) library to connect to the SAP system. The connection address

for an SAP system is denoted as a connection string.

Connecting to a specific application server

In its basic form, a connection string consists of the host name (or IP name) of an

SAP application server; for example:

/H/hemlock.tivlab.raleigh.ibm.com

This type of connection string works only in very simple network environments,

where all application servers can be reached directly through TCP/IP. Usually,

modern companies use more complex network topologies, with a number of small

sub-networks, which cannot communicate directly through TCP/IP. To support this

type of network, the SAP RFC library supports SAP routers, which are placed at

the boundaries of the sub-networks and act as proxies. For this type of network,

the connection string is a composite of basic connection strings for each SAP

router, followed by the basic connection string for the target SAP system; for

example:

/H/litespeed/H/amsaix33/H/hemlock.tivlab.raleigh.ibm.com

Moreover, you can secure the SAP routers with passwords, to prevent

unauthorized access. In this case, the basic connection string for the SAP router is

followed by /P/ and the password of the router.

Note: The SAP RFC library limits the length of the connection string to a

maximum of 128 characters. This is a real limitation in complex network

environments. As a workaround, it is recommended to use simple host

names, without the domain name whenever possible. Alternatively, you can

use the IP address, but this is not recommended, because it is difficult to

maintain.

Configuration options usage


Tivoli Workload Scheduler for Applications for SAP supports both types of

connection strings, basic and composite, where:

r3host The connection string.

r3instance The SAP instance number.

r3sid The SAP system ID.

For example:

r3host=/H/litespeed/H/amsaix33/H/hemlock.tivlab.raleigh.ibm.com

r3instance=00

r3sid=TV1

Connecting to a logon group

In large SAP installations, the application servers are usually configured in logon

groups for load balancing and fault-tolerance purposes. Load balancing is done by

a dedicated server, called the message server. The message server automatically

assigns users to the application server with the least workload of the logon group

it controls.

Set the following options to configure r3batch to connect to a logon group:

r3host The hostname of the message server.

r3group The name of the logon group.

r3sid The SAP system ID.

For example:

r3host=pwdf0647.wdf.sap-ag.de

r3group=PUBLIC

r3sid=QB6

Connecting to a specific application server


Logon groups


Chapter 15. Managing the running of SAP jobs

This chapter describes how to perform the following tasks:

v “Defining a job that runs an SAP job”

v “Editing a standard SAP job” on page 128

v “Task string to define SAP jobs” on page 129

v “Rerunning an SAP job” on page 137

To manage the running of jobs on an SAP workstation from Tivoli Workload

Scheduler, you must define the following:

Jobs in SAP that you want to run under Tivoli Workload Scheduler control

You can define these jobs using standard SAP tools, the SAP-specific panels of

the Job Scheduling Console, or the Tivoli Dynamic Workload Console.

Jobs in Tivoli Workload Scheduler that correspond to the jobs in SAP

The Tivoli Workload Scheduler job definitions are used in scheduling and

defining dependencies, but the SAP jobs are actually run.

Defining a job that runs an SAP job

Using the Job Scheduling Console, you can define a Tivoli Workload Scheduler job

that runs an SAP job. The SAP job can:

v Already exist in the SAP system and be identified using the information defined

in the SAP Job Identity group on page 119

v Be created directly by clicking New in the Task page on page 119.

To define a job that runs an SAP job, perform the following steps:


Definition.

2. Select an engine. The Properties - Job Definition panel is displayed.





General page




Task Type

Select SAP.

Name

Type the name of the Tivoli Workload Scheduler job that runs the SAP job

whose name you provide in the Job Name field of the Task page. The name

must start with a letter, and can contain alphanumeric characters, dashes,

and underscores. The maximum length is 40 characters.

Workstation Name

Type the name of the SAP workstation where the Tivoli Workload Scheduler

job runs or use ellipsis (...) to display a list of SAP workstations.

Figure 9. The General page of the Properties - Job Definition panel

Defining a job that runs SAP job


Description

Type a description of the job. The maximum length is 120 characters.v Login group:

Login Type the name of the user who launches the job. The maximum length is

47 characters. Specify a user that can log on to the workstation where

the job runs. For more information, see Tivoli Workload Scheduler: Job

Scheduling Console User’s Guide.

Add Parameter

Adds a parameter to the login field.v Recovery Options group:

Select the recovery option you want to associate with the job if it ends in error.

Possible values are:

– Stop. Do not continue with the next job. This is the default value.

– Continue. Continue with the next job.

– Rerun. Rerun the job.

Message






Job

Click ellipsis (...) to display a list of recovery jobs from which to select the

recovery job to run if the job you are defining ends in error. Recovery jobs

are run only once for each instance of the job.

Workstation Name








job workstation.


Status mode.

General page

Chapter 15. Managing the running of SAP jobs 117

Task page

Use the Task page to provide task information for the SAP job that is run by the

Tivoli Workload Scheduler job defined in the General page. This page is not

available until a workstation has been specified in the General page.


v Task Type group:

Figure 10. The Task page of the Properties - Job Definition panel

Task page


This information field indicates that the job is SAP task type. The task type

depends on the SAP system where you defined the job.

v R/3 Job Type group:

R/3 Job Type

Select Standard R/3 job. You cannot create on the SAP system database

either the Business Warehouse InfoPackage or the Business Warehouse

Process Chain job type using the Job Scheduling Console.v R/3 Job Identity group:

Job Name

Type the name of the SAP jobs. Click ellipsis (...) to display a list of SAP job

already defined in the SAP system whose status is scheduled.

Job ID

Displays the job identifier assigned by the SAP system when the creation is

completed.

User Name

Type the name of an SAP user. The default value is the value of the r3user

option contained in the WKSTNAME_r3batch.opts file. The default value is

displayed when the creation is completed.

Job Action

Click New to create a standard SAP job in the SAP database. The SAP Job

Definition panel is displayed, as shown in Figure 11 on page 121.v Debug and Setting Options group:

Trace

Select to create a trace file dev_rfc in the Tivoli Workload Scheduler home

directory. Ensure you delete the trace option from the job after you have

performed debug procedures. The dev_rfc file can become very large and

cause problems to your system.

Debug

Select to include additional debug information in the stdlist file of the job.

Disable BDC Wait

Select to disable the BDC Wait option for the job. For details, refer to

Chapter 19, “Using the BDC Wait option,” on page 173.

Launch Job Immediately

Select to launch the SAP job immediately.v R3 Command Line group:

R3 Command Line

Type any flags that are valid for the SAP command line, such as -client 500

-exec_client 500 -s 1 -s1 program=BTCTEST -s1 type=a -flag type=exec.

If you specified a value for a parameter both using the GUI field and the R3

command line, the product uses the value specified on the command line.

See Table 35 on page 131 to know which flags are supported by the GUI and

which flags are supported by the command line.v Job Options group:

Job Spoolist

Select to retrieve the spool list in the job log. Possible values are:

– Blank. If you select blank, Tivoli Workload Scheduler uses the value you

set for the retrieve_spoollist option. If you did not define the

retrieve_spoollist option, the value used is enabled.

– Enabled

Task page


– Disabled

PChain Log (for job process chain only)

Select it to retrieve the job process chain log. Possible values are:

– Blank.

– Enabled

– Disabled

Job Log

Select to retrieve the job log. Possible values are:

– Blank. If you select blank, Tivoli Workload Scheduler uses the value you

set for the retrieve_spoollist option. If you did not define the

retrieve_joblog option, the value used is enabled.

– Enabled

– Disabled

Job Class

Displays the class assigned to the job in the Job Class field in the R/3 Job

page. This represents the priority with which the job runs in the SAP system.


Blank Low priority. This is the default value.

A High priority

B Medium priority

C Low priorityv Return Code Mapping group:

Expression

Type a logical expression that defines the success condition. Allowed

operators are comparison operators (=, != or <>, >, >=, <, <=) and logical

operators (AND, OR, NOT). For example, the expression RC>= 6 indicates

that a return code greater than or equal to 6 means the task is successful.

Complete the information as described in the following sections:

v “R/3 Job page” on page 121

v “Steps” on page 122

Task page


||

|

|

|

R/3 Job page

Use the R/3 Job page to define or modify the native SAP job to run under the

control of Tivoli Workload Scheduler (as a task of the job you specified in the

General tab).


Job Name Type the name of the SAP job.

Job Class Type the class of the SAP job. This represents the priority with

which the job runs in the SAP system. Possible values are:

Blank Low priority. This is the default value.

A High priority

B Medium priority

C Low priority

Event ID Displays the identifier of the event defined in the SAP system.

Event Parameter

Displays the parameter of the event defined in the SAP system.

Figure 11. The SAP Job Definition panel

Task page


Client Displays the value indicated in the R3Client option of the

workstation_r3batch.opts option file. This field is filled when the job

creation completes.

Target Host Type the name of the SAP workstation where the job is to run. The

name has the format hostname_SAPsystemname_SAPsystemnumber,

as for example amss80a0_gs7_90.

If you specify a target host, you cannot set a server group.

Server Group Type the name of the SAP server group to assign to the job. This

means that when the job is launched, the SAP system runs it on an

application server that belongs to that group, balancing the

workload among the various application servers. This field is

available from SAP Basis version 6.10 with SP 40 (for more details,

refer to “Balancing SAP workload using server groups” on page

144).

The field is case sensitive. To display a list of available SAP server

groups, click ellipsis (...). If you specify a server group, you cannot

set a target host.

Steps

Use the Steps page to define one or more ABAPs, external programs, or external

commands for the SAP job.

Task page


|

||||||||

|||


v Common Value group:

Type Specify the type of programs contained in the job. Possible

values are:

– ABAP

– External programs

– External commands

Name The name of the SAP step. If you are creating an ABAP jobs type

its name or use ellipsis (...) to display a list of ABAP job. If you

are creating an external command, use ellipsis (...) to display a

list of external commands. If you are creating an external

program, type its name.

Figure 12. The Steps page of the SAP Job Definition panel

Task page


User The name of the SAP user who launches the step.

Var / Parm Type any variants or parameters for the step. Variants are used

with ABAP modules, and parameters are used with external

programs and external commands. Not all ABAPs require

variants and not all external programs and external commands

require parameters. Click ellipsis (...) to display a list of variants

associated with the ABAP. Use this list to select, create, or

change a variant. See “Managing SAP variants using the Job

Scheduling Console” on page 126 for details.

Target Host Type the SAP target host workstation for this step. This option is

applicable to external programs and external commands.v Print Parameters group (for ABAP programs only):

Number of Copies

Type the number of copies you want to print. The default value is 1.

List Lines

Type the number of list lines.

Output Device

Type the name of the printer or fax. Click ellipsis (...) to display a list.

Columns

Type the number of characters per list line.

Name Spool Request

Type the name of the spool request. Set this only if you do not want to print

immediately.

Text Cover Page

Type the description text of the spool request. This text appears on the

standard cover page.

Recipient

Type the recipient name for the SAP cover sheet.

Spool Data Set

Type the spool Data Set name.

Print Formatting

Specify the page format of the output. Depending on the printer connected,

you can set different formats with different maximum page length and width

values in this field.

Authorization

Type the authorization for the spool request. Only users with this

authorization can view the contents of the request.

Department

Specify the department name for the SAP cover sheet.

Print Parameters Flags

Click Print Parameter Flags to set the flags for the print parameters.

Task page


Archiving Mode

Displays the archive mode for the print parameters.

SAP Cover Page

Specify the SAP cover page. Possible values are:

' ' Blank. Does not use any cover page.

'X' Prints the host cover page.

'D' Prints the default host cover page.

Spool Retention Period

Specify how long the spool is retained after printing.

Spool Request Priority

Specify the priority for the print. This field is available for jobs created

using SAP BC-XBP 2.0. The default value is 8.

Delete After Printing

Select it to delete the print job after printing.

Print Immediately

Select it to print the job immediately.

Selection Cover Page

Select it to select a cover page for the print job.

New Spool List

Select it to create a new spool list for the print job. This field is available

for jobs created using SAP BC-XBP 2.0.

Host Spool Cover Page

Type the value to associate to the cover page of the host spool. This field

is available for jobs created using SAP BC-XBP 2.0. Possible values are:



'D' Prints the default host cover page.v Control Flags group (for external programs only):

Job to wait for Ext Program to End

Select it to run the SAP job when the external program ends.

Figure 13. The Print Parameter Flags panel

Task page


Output Joblog

Select it to log the output of the job in the SAP system.

Error Output Joblog

Select it to log all the external errors in the SAP system.

Activate Trace

Select it to activate the traces.

Managing SAP variants using the Job Scheduling Console

This section describes how to manage variants using the Tivoli Job Scheduling

Console:

1. In the step page of the SAP Job Definition panel, click the Var/Parm (...) ellipsis.

The Variant List panel is displayed listing all the variants associated with the

ABAP specified in the Name field.

2. From this panel, you can perform the following actions:

Set To associate the value chosen from the list to the ABAP.

Refresh

To refresh the content of the variant list with the information contained

in the SAP database.

New To create a new variant as described in “Creating or editing a variant.”

View To display information on an existing variant.

Edit To modify information on an existing variant as described in “Creating

or editing a variant.”

Delete To delete a variant.

Creating or editing a variant

This section describes how to create or edit a variant. To create or edit a variant


Figure 14. The Variant List panel

Task page


1. In the Variant List panel, click New or Edit. A Variant Frame panel similar to

that shown in Figure 15 is displayed. If you are editing an existing variant, the

fields and selections are not empty.

2. The panel consists of the following pages:

v Variant Information:

a. Enter or modify the variant name and description.

b. Optionally, check a Properties box:

Background

The variant can only be used in background processing.

Protected

The variant is protected against being changed by other users.

Invisible

The variant will not be displayed in the F4 value list in the SAP GUI.

Extended

Allows for the use of placeholders and counters as variant values. If

you check this box, counter becomes available.For extended variants, you can use placeholders and counters that

eliminate the error-prone task of adjusting values and therefore minimize

the effort for variant maintenance. Placeholders and counters are

preprocessed by Tivoli Workload Scheduler and the values are

automatically adjusted when the job is launched. Supported placeholders

and counters are:

Table 34. Placeholders and counters for extended variants

Symbol Meaning Syntax

$S Timestamp YYYYMMDDHHMM

$D Day of the month DD

$_D Date YYYYMMDD

Figure 15. The Variant Information page of the Variant List panel



Table 34. Placeholders and counters for extended variants (continued)

Symbol Meaning Syntax

$M Month MM

$Y Year YY

$_Y Year YYYY

$H Hour HH

$T Minute MM

$_T Time HHMMSS

$Nx Counters 10 counters: $N0 - $N9 ($N = $N0)

$(date expression) Date expression Like the datecalc command. Enclosed

within $( and ).

$[arithmetic expression] Arithmetic expression Arithmetic expressions allowing for +,

−, *, and / operations between

integers and counters.

v Variant Values:

In the Variant Values page, the fields and values are dynamically built

through r3batch depending on the characteristics of the variant or step and

are identical to the ones in the equivalent SAP panel.

Editing a standard SAP job

To edit a standard SAP job, perform the following steps:

1. In the Work with engines pane, select an engine → database list → job definition

list. The list of job pane displays all the available jobs.

2. Double-click the SAP job you want to edit. The Properties - Job Definition

panel is displayed.


v “General page” on page 116.

v “Task page” on page 118.3. Modify the information contained in the pages as appropriate.

4. To modify the SAP job information in the SAP database, on the Task page click

Edit. The SAP Job definition panel is displayed.

5. Modify the information described on the following pages as appropriate:

v “R/3 Job page” on page 121.

v “Steps” on page 122.

In the R/3 job page, when you modify the Job Name or the Target Host and

click OK, the Job ID in the Task page is automatically replaced with the one

associated to the new job name.

In the Steps page, for each step you modify, click the Modify Step icon. This

operation saves the new step information in the SAP database. For each step

you add or delete, the Job ID in the Task page is automatically modified.

6. Click OK. The Properties - Job Definition dialog is displayed.

7. Click OK.



Task string to define SAP jobs

This section describes the task string parameters that define and control the

running of SAP jobs. You must specify them in the following places when you

define their associated Tivoli Workload Scheduler jobs:

v In the Command field of the Task page of the Properties - Job Definition panel,

if you use the Job Scheduling Console and selected Other (and not SAP) for a

new job definition.

v In the R3 Command Line field of the Task page of the Properties - Job

Definition panel, if you use the Job Scheduling Console and selected SAP for a

new job definition.





environment. The following is an example of a JOBREC statement:

JOBREC

JOBCMD(’/-job job_name -user user_name -i job_ID -c class_value’)


where:

class_value The priority with which the job runs in the SAP system. For

details, see Table 35.

job_ID The unique SAP job ID. For details, see Table 35.

job_name The name of the SAP job to run. For details, see Table 35.

user_name The SAP user who owns the target job. For details, see Table 35.

TWS_user_name


r3batch access method from the end-to-end scheduling

environment.

The string syntax is the following:

Job definition syntax

�� -job job_name

-i

job_ID

-id

-user

user_name �

� -host

host_name

-ts

-sg

server_group �

� -client

source_client

-exec_client

target_client �

Task string parameters for SAP jobs


|||

|||

|

|||

||

||

||

||||

||

� -c

class_value

-s

starting_step_number �

� -bdc_job_status_failed

bdc_processing

-nobdc

-nobdcwait

�

�

�

-sStep_number

attribute_name

=attribute_value

�

� -vStep_number

variant_name

-vtxtStep_number

variant_description �

� -vparStep_number

name=variant_value �

� -vselStep_number

name=

i

#operation#lowest

e

#highest

�

� -recipient

R/3_login_name

-rectype

recipient_type �

� -flag

reccp

recbl

-flag recex

-flag recnf �

� -flag

im

immed

-flag

enable_joblog

disable_joblog

�

� -flag

enable_spoollist

disable_spoollist

-flag

pc_launch

-debug �



11

� -tracelvl

1

2

3

-rfctrace ��

Table 35 describes the parameters for the task string to define SAP jobs.

Notes:

1. You can specify both -i or -id and -user in the same job definition, but the

user name is ignored.

2. When you specify the job ID, -client and -exec_client are ignored because

the ID is unique for the entire SAP system.

3. Typically, the -debug and -trace options are for debugging the extended agent

and should not be used in standard production.

Table 35. Task string parameters for SAP jobs

Section Parameters Description

GUI

Support

JOB -job job_name The name of the job to run. This parameter is

mandatory.

U

-i job_ID

-id job_ID

The unique SAP job ID. Specify this parameter if you

are submitting a job that refers to a predefined job

template stored in the SAP database for which you

want to change a parameter.

U

-user user_name The SAP user who owns the target job. Use this

parameter when the target SAP system has only one

job with the specified name for the specified user. This

parameter has no effect if a job ID is specified in the

job definition.

U

-host host_name

-ts host_name

The name of the SAP workstation where the job is to

be run. host_name has the format

hostname_SAPsystemname_SAPsystemnumber.

For example, the name of a host might be

amss80a0_gs7_90

These parameters are mutually exclusive with -sg.

U

-sg server_group The name of the SAP server group where the job is to

be run. Use this parameter to run the job on an

application server that belongs to the group. The

server group must exist on the SAP system, otherwise

an error code is returned and the job is not launched.

This parameter is case-sensitive and can be up to 20

characters. It is mutually exclusive with -host and -ts.

U

-client source_client The number that identifies the SAP client where the

job definition is to be found, regardless of the client

number defined by the r3client keyword in the

options file. This parameter has no effect if a job ID is

specified in the job definition.



|

||||||

||

|

Table 35. Task string parameters for SAP jobs (continued)


GUI

Support

JOB -exec_client target_client The number that identifies the SAP client where the

job is to be run, regardless of the client number

defined by the r3client keyword in the options file.

This parameter has no effect if a job ID is specified in

the job definition.

-rfc_client rfc_logon_client The number that identifies the SAP client to be used

for RFC logon. This value overwrites the value

specified by the r3client keyword in the corresponding

r3batch options file.

-c class_value The priority with which the job runs in the SAP

system. Possible values are:

A High priority

B Medium priority

C Low priority. This is the default value.

U

-bdc_job_status_failed bdc_processing How Tivoli Workload Scheduler sets the completion

status of a job running BDC sessions, according to a

possible BDC processing failure. The allowed values

are:

n If at least n BDC sessions failed (where n is

an integer greater than 0), Tivoli Workload

Scheduler sets the job completion status as

failed.

all If all the BDC sessions failed, Tivoli Workload


failed.

ignore When all the BDC sessions complete,

regardless of their status, Tivoli Workload


successful. This is the default.

If -nobdc or -nobdcwait is set, this option is ignored.

U

-nobdc

-nobdcwait

Disables the BDC Wait option (enabled by default) to

have the job considered as completed even if not all

its BDC sessions have ended.

U



||

1111111111111111111

1

1



GUI

Support

STEP -s starting_step_number The number of the starting step. U

-sstep_number

attribute_name=attribute_value

The step number and its attributes, where:

step_number

The number of the step being defined. Each step is

identified by a sequential number (1, 2, 3, ...n)

using the step number

attribute_name

The name of the attribute.

attribute_value

The value of the attribute. It is optional for some

attributes.

Attributes can be defined in any order, but cannot be

repeated for the same step. Attribute validation is

performed before the job is created in the SAP system.

If the validation fails, the Tivoli Workload Scheduler

job goes into the ABEND state. For a detailed

description of each attribute and its value, see

“Defining attributes for ABAP steps” on page 156 and

“Defining attributes for external programs and

external commands steps” on page 159.

For example, the following step (step 8) is an ABAP

module running the report MYPGM and has two

attributes, only one of which has a value.

-s8 type=A -s8 program=MYPGM

-s8 pr_cover="My title" -s8 pr_immed

U





GUI

Support

VARIANT -vstep_number name The variant name for the specified step number. U

-vtxtstep_number variant_description The textual description of the variant, in the Tivoli

Workload Scheduler logon language (customizable

with the TWSXA_LANG option of r3batch). The

maximum length is 30 characters.

U

-vparstep_number name=value For ABAP modules only. The value for a variant

parameter for the specified step number. This

parameter is mandatory when creating a new variant.

See “Defining attributes for ABAP steps” on page 156

for a complete list of the supported attributes for

ABAP steps.

U

-vselstep_number

name=sign#operation#lowest[#highest]

For ABAP modules only. The value for a variant

selection option for the specified step number.

sign Sign of the operation. Possible values are:

I Include

E Exclude

operation


EQ Equals

NE Not equal to

BT Between

NB Not between

LT Less than

LE Less than or equal to

GT Greater than

GE Greater than or equal to

CP Contains pattern

NP Does not contain pattern

lowest Low value of the selection. You can use up to

45 characters.

highest High value of the selection. You can use up

to 45 characters. This attribute is optional.For a complete list of the supported attributes for

ABAP steps, see“Defining attributes for ABAP steps”

on page 156.

U





GUI

Support

SPOOL -recipient name The login name of an SAP user.

-flag {recp|recbl} Specifies how the spool list is sent to the recipient.


recp The spool list is sent as a copy.

recbl The spool list is sent as a blind copy.

-flag recex Specifies that the spool list is sent as an express

message to the recipient.

-flag recnf Specifies that the recipient is not allowed to forward

the spool list.

-rectype type Specifies the recipient type. Possible values are:

' ' SAP user (default value)

'B' SAP user

'C' Shared distribution list

'D' X.500 address

'G' Organization object/ID

'H' Organization unit

'I' SAP object

'L' Telex number

'O' SAPOffice user

'P' Private distribution list

'R' SAP user in another SAP system

'U' Internet address

'1' Other recipient type

FLAGS -flag im

-flag immed

Specifies to launch job immediately, meaning that if

there are no spare work processes, the job fails.

U

-flag enable_joblog

-flag disable_joblog

Enables or disables retrieval of the joblog. U

-flag enable_spoollist

-flag disable_spoollist

Enables or disables retrieval of the spool lists of the

job.

U

-flag pc_launch Specifies to launch child jobs that are in scheduled

state.

ON The product launches child jobs that are in

scheduled state.

OFF The product does not launch child jobs that

are in scheduled state. This is the default

value.Note: You can use this option only if you activated

the parent-child feature on the SAP system. On the

XBP 2.0 SAP system you can activate this feature

using the INITXBP2 ABAP report





GUI

Support

TRACING -debug Enables maximum trace level. U

-tracelvl 1|2|3 Specifies the trace setting for the job. Possible values

are:

1 Only error messages are written in the trace

file. This is the default.

2 Informational messages and warnings are

also written in the trace file.

3 A most verbose debug output is written in

the trace file.For detailed information, refer to Chapter 29,

“Configuring the tracing utility,” on page 247.

U

-rfctrace

trace

Enables RFC trace.

The following is an example for an SAP job named BVTTEST with ID 03102401 and

user myuser:

-job BVTTEST –i 03102401 -user myuser -debug



Rerunning an SAP job

To rerun an SAP job, you can use one of the following consoles:

conman

For details, refer to the Tivoli Workload Scheduler: Reference Guide.

Job Scheduling Console

For details, refer to the Tivoli Workload Scheduler: Reference Guide.

Tivoli Dynamic Workload Console

For details, refer to the Tivoli Dynamic Workload Console online help.

Note: By default, if you specify a job step to rerun, the new job is assigned the

name of the step you indicated. To keep the original job name, set the Tivoli

Workload Scheduler global option enRetainNameOnRerunFrom to yes. For

details about this option, see the Tivoli Workload Scheduler: Planning and

Installation Guide.

Refer to the following sections for details about:

v “Rerunning a standard SAP job”

v “Rerunning a process chain job” on page 138

Rerunning a standard SAP job

For an SAP extended agent, a step is the numeric step of the SAP instruction from

which a job can be restarted. Before you rerun an SAP job with Tivoli Workload

Scheduler, you have the option of providing a step name for the job. This affects

r3batch in the following ways:

v If you use a step name that is up to 9 digits (or 8 digits preceded by a character)

in length, this name is used as the starting step number for the rerunning job

v If you use any different format, the name is ignored and the job is rerun starting

from the first step

For example, to rerun a job from the third step, you can use: A03, 3, 00003, or H3.

When r3batch reruns a job from its first step, either because you specified it as the

starting step or because no starting step was specified, it uses the new copy feature,

if applicable. If the starting step is greater than one, r3batch uses the old copy to

rerun the job.

For a description about the difference between the new and old copy of a

rerunning job, refer to “Old copy and new copy of a rerunning job.”

Old copy and new copy of a rerunning job

When the access method for SAP launches a job, it makes a copy of a template job

and runs it.

The new copy feature is available for SAP versions 3.1i, and later. It copies an entire

job, preserving steps, job class, and all print and archive parameters. It is

performed using a new SAP function module that is part of the SAP Support

Package as stated in the SAP Notes 399449 and 430087.

The old copy feature, instead, based on standard SAP function modules, creates a

new SAP job and adds the steps with a loop that starts from the step name or

number you specified. Be aware that, unless you have XBP 2.0 support:

v The old copy does not preserve all the print and archive parameters.



1

11

11

11

11111

1

v The job class of the copy is always set to class C.

Refer to “Print parameter and job class issues” on page 102 to learn how to resolve

the issue of lost job class and print and archive parameters.

SAP Note 758829 is required to ensure proper operation of the new copy and old

copy features. See also Table 69 on page 257.

Rerunning a process chain job

Table 36 shows the action performed when you rerun a Tivoli Workload Scheduler

job that submits a process chain, depending on the settings you specify.

Table 36. Actions performed when you rerun a process chain job

Action performed Description and setting

A new process chain

instance is submitted

Tivoli Workload Scheduler creates another process chain instance

and submits it to be run again. This action occurs when:

v You specify RERUNvalue as the step to rerun, where value is any

value you want. This setting overrides the settings in the job

definition and options file, if any.

In an end-to-end environment, you can perform this action on a

centralized job by adding the following parameter to the script

file:

-flag pchain_rerun

v In the job definition, you set -flag pchain_rerun. This setting

overrides the setting in the options file, if any. For a description

of this parameter, see Table 41 on page 170.

v In the options file, you set the pchain_recover option to rerun.

For a description of this option, refer to Table 33 on page 106.

The original process

chain is rerun from

the failed processes

Tivoli Workload Scheduler restarts the original process chain from

the failed processes to the end. In this way, after you detected the

error that caused the failure and performed the recovery action,

you can rerun the process chain job from the failed processes and

have its run completed.

This action is performed only if at least one process in the process

chain did not complete successfully. It occurs when:

v You specify RESTARTvalue as the step to rerun, where value is

any value you want. This setting overrides the settings in the

job definition and options file, if any.



file:

-flag pchain_restart

v In the job definition, you set -flag pchain_restart. This setting

overrides the setting in the options file, if any. For a description

of this parameter, see Table 41 on page 170.

v In the options file, you set the pchain_recover option to

restart. For a description of this option, refer to Table 33 on

page 106.

Old copy and new copy of a rerunning job


1

11

11

11

1111

111

111

1

111

11

111

11111

11

111

111

1

111

111

Table 36. Actions performed when you rerun a process chain job (continued)

Action performed Description and setting

The process that you

specify is restarted

Tivoli Workload Scheduler restarts the process of the original

process chain that you specify, and monitors the process chain run

until its final state.

This action occurs when you specify PROCESSprocessID as the step

to rerun, where processID is the identifier of the process you

want. The process IDs are shown in the Tivoli Workload Scheduler

job log, as follows:

+++ EEWO1071I Start of process chain PCHAIN1

Process Chain PCHAIN1 (Log ID:D3C0ZWAYESD58PXOYPEOGNZK7).

--------------------------

Process Type: TRIGGER.

Process Variant: PCHAIN1_STARTER.

Actual State: F.

...

>> Process ID: 3.

Process Type: ABAP.

Process Variant: Z_PCHAIN1_NODE3.

Actual State: F.

Instance: D3C0ZXL3IJ8LR5O9Q1D9A4Y4N.

>> Process ID: 4.

Process Type: ABAP.

Process Variant: Z_PCHAIN1_NODE1.

Actual State: .

Instance: D3C0ZZKS0RR88DKRJQ09Z1WW7.

+++ EEWO1072I End of process chain PCHAIN1



file:

-pchain_pid processID

The status and details

of the original process

chain are updated

Tivoli Workload Scheduler monitors the original process chain

until its final status.

This action occurs when:

v You specify REFRESHvalue as the step to rerun, where value is

any value you want. This setting overrides the setting in the job

definition, if any.



file:

-flag pchain_refresh

v In the job definition, you set -flag pchain_refresh. For a

description of this parameter, see Table 41 on page 170.

Notes:

1. By default, if you do not specify any setting, rerunning a process chain job

corresponds to submitting a new process chain instance.

2. If you kill a Tivoli Workload Scheduler job that submits a process chain, the

process chain is removed from schedule in the SAP Business Information

Warehouse system. To restart the same process chain instance with r3batch, you

require at least the following SAP Business Information Warehouse versions:

v 3.0 with SP25

v 3.1 with SP19

Rerunning process chain job


1

11

11111

1111

11111111111111111111

111

1

111

11

1

111

111

1

111

1

11

111111

v 3.5 with SP10

v 7.0

If your version of SAP Business Information Warehouse is earlier, you can

restart the process chain only manually, through the SAP graphical interface.

Business scenario: rerunning the original process chain job from

the failed process

As a scheduling administrator, you are responsible for managing batch jobs in SAP

and non-SAP systems. The workflow is one or more job streams in Tivoli Workload

Scheduler. A job stream contains jobs that collect and prepare data for month-end

closing over all sales channels. The month-end closing report requires data to be

collected from several sales and distribution systems. Data is collected using local

and remote process chains in the SAP Business Intelligence system. The process

chains include a set of Infopackages, ABAP reports, and operating system jobs to

sort the report data by a logical hierarchy.

To administer from a single point of control, you link the SAP process chains to

Tivoli Workload Scheduler through Tivoli Workload Scheduler for Applications.

During batch processing, a Tivoli Workload Scheduler job comprising a process

chain, failed. Optionally, you can see what processes failed either through the

Tivoli Dynamic Workload Console (for details, see “Displaying details about a

process chain job” on page 142) or the job log. You ask the SAP administrator to fix

the cause of the error, then you rerun the Tivoli Workload Scheduler job by setting

the step as RESTARTvalue. In this way, the original process chain is rerun from the

failed processes and continues until the ending step.

Business scenario: restarting a process of the process chain

You might decide to restart a single process as a preparation step before restarting

the failed processes of a process chain. A failed process might have corrupted some

data, so you run the single process to restore the data and set up the required

system state before you rerun the other processes in the process chain.

Suppose you are using InfoPackages and process chains to extract data from one or

several sources and you want to transform this data into managerial reports, for

example by using aggregate functions. If the process that transforms this data fails,

it might corrupt the data that the preceding InfoPacakge process had successfully

extracted. After fixing the problem with the transformation process, you must

restart the InfoPackage extraction process to reload the data, even though this

extraction process had completed successfully before. Restart the failed

transformation process only after the data has been reloaded, either by restarting

the failed processes of the process chain or restarting just the failed transformation

process.

Rerunning process chain job


11

11

1111111111

11

1111111

11111

1111111111

Chapter 16. Managing SAP jobs

This chapter describes how to perform the following tasks:

v “Displaying details about a standard SAP job”

v “Displaying details about a process chain job” on page 142

v “Verifying the status of a standard SAP job” on page 144

v “Deleting a standard SAP job from the SAP database” on page 144

v “Balancing SAP workload using server groups” on page 144

v “Raising an SAP event” on page 145

v “Mapping between Tivoli Workload Scheduler and SAP job states” on page 145

v “Killing an SAP job instance” on page 147

Displaying details about a standard SAP job

To display details about a standard SAP job, perform the following steps:


list. The list of job pane displays the available jobs.

2. Double-click the SAP job whose details you want to display. The Properties -

Job Definition panel is displayed.


v “General page” on page 116

v “Task page” on page 1183. On the Task page, click Details. The Details panel is displayed. It contains all

the information relevant for the job.

4. Click OK. The Properties - Job Definition dialog is displayed.

5. Click OK.


1

Displaying details about a process chain job

To display details about an SAP process chain that you scheduled as a Tivoli

Workload Scheduler job, perform the following steps from the Tivoli Dynamic

Workload Console.

Note: You can perform these steps only if you:

v Did not set the pchain_details option to OFF in the job definition. For

more information about this option, refer to “Defining the common

options” on page 106.

v Customized the Browse Jobs tasks that you created before installing Tivoli

Workload Scheduler for Applications 8.4 Fix Pack 1 to show the Job Type

column. For details about how to customize the task properties, refer to

the Tivoli Dynamic Workload Console online help.1. From your Tivoli Workload Scheduler list of tasks, click the Jobs task that you

want to run.

2. Enter any information required and click OK. The table of results for the task is

displayed:

3. For each process chain job, the Job Type column shows a hyperlink named

SAP Process Chain. Click the hyperlink for the job whose details you want to

display. A panel like the following opens:

Figure 16. Tivoli Dynamic Workload Console - Table of results

Displaying details about process chain jobs


1

111

1

111

1

111

1111

11

111

1111

You are shown the details of the process chain job.

Note: Tivoli Workload Scheduler for Applications monitors the process chain

job until the job completes. The details shown reflect the last monitoring

process performed.

4. If the process chain contains local subchains, a hyperlink is displayed for each

one. Click the hyperlink you want, to display details about the corresponding

subchain job.

Alternatively, you can display the process chain details from the job properties

panel by clicking the hyperlink that is shown under SAP Job Details.

Figure 17. Tivoli Dynamic Workload Console - Details of a process chain job

Displaying details about process chain jobs

Chapter 16. Managing SAP jobs 143

1

1111

111

111

11

Verifying the status of a standard SAP job

To verify the status of a standard SAP job, perform the following steps:



2. Double-click the SAP job whose status you want to display. The Properties - Job

Definition panel is displayed.



v “Task page” on page 1183. In the Task page click Status. The SAP Job Status panel is displayed with the

status of the job.

4. Click OK. The Properties- Job Definition dialog is displayed.

5. Click OK.

Deleting a standard SAP job from the SAP database

To delete a standard SAP job from the SAP database, perform the following steps:



2. Double-click the SAP job you want to delete. The Properties - Job Definition

panel is displayed.



v “Task page” on page 1183. In the Task page click Delete, to delete the SAP job displayed in the Job Name

field. To delete a job different from the one displayed in the Job Name field,

click ellipsis (...) to display a list of available jobs. Select the job you want to

delete.


5. Click OK.

Balancing SAP workload using server groups

SAP jobs run on application servers that host work processes of type batch. Critical

batch jobs are run in specific time frames, on specific application servers. With SAP

Basis version 6.10 and later, application servers can be assigned to server groups.

With Tivoli Workload Scheduler for Applications, you can assign a server group to

a job. In this way, when a job is launched, the SAP system runs it on an

application server that belongs to that group, balancing the workload among the

various application servers.

If the application servers defined in a group are modified in the SAP system, the

job defined as belonging to that server group is not affected and does not need to

be modified. The batch execution targets are reorganized in the SAP system

without having to change job definitions in Tivoli Workload Scheduler for

Applications.

This function is supported with the following versions of SAP:

v SAP Basis 6.10, with Service Pack 40



Verifying the status of a standard SAP job


|

|||||||

|||||

||||

v SAP Basis 7.00, and later

Mapping between Tivoli Workload Scheduler and SAP job states

When an SAP job is launched by Tivoli Workload Scheduler, you can monitor its

progress. The status transitions in Tivoli Workload Scheduler (internal status) and

the corresponding SAP status are listed in Table 37.

Table 37. Status transitions in Tivoli Workload Scheduler (internal status) and the

corresponding SAP R/3 status

Tivoli Workload Scheduler Job State SAP Job State

INTRO Not Available

WAIT Ready, Release

EXEC Active

SUCC Finished

ABEND Canceled

The INTRO state indicates that Tivoli Workload Scheduler is in the process of

introducing the job, but in SAP, the job has not yet entered the ready state. Because

it takes some time to get a job queued and into the ready column, the INTRO state

might last a few minutes if the SAP system is particularly busy.

Even if a job is finished in SAP, Tivoli Workload Scheduler keeps it in the EXEC

state if its BDC sessions are not complete and you have not selected the Disable

BDC Wait option. To use this option, see Chapter 19, “Using the BDC Wait

option,” on page 173.

Raising an SAP event

You can raise events on XBP 2.0 SAP jobs in the Tivoli Workload Scheduler

database in one of the following ways:

Using the Raise Event function


1. On the SAP system, create a job that has as start condition an SAP

event. When you create this job its status is released.

2. Check that this job was not intercepted by the interception function.

3. In the Work with engines pane, select an engine → database list → job

definition list. The list of job pane displays the available jobs.

4. Select a Tivoli Workload Scheduler job whose workstation has been

defined to connect to the SAP system.

5. Right-click the job and select Raise Event.

The Raise Event panel opens.

Balancing SAP workload using server groups


|


Event ID

The identifier of the event that is to be raised.

Event Parameter

The parameter of the event that is to be raised.6. Click OK. The event is raised.

Creating a job that launches a Windows or UNIX command that performs a raise

event


1. In the Actions list of the Job Scheduling Console main window, select

New Job Definition.




v “Task page” on page 1183. Use the General page to provide general information about the new job

definition.

4. Use the Task page to provide task information for the job.

5. In the Task page, select Command and type the following command

that performs the raise event in the command string:

TWShome/methods/r3event -c workstation_name -u user_name

-e SAP_event_ID -p parameter

where:

workstation_name

The name of the workstation where the SAP R/3 job is defined.

user_name

The name of the SAP user with which the access method connects

to the SAP system. This is the name specified in the r3user option.

SAP_event_ID

The identifier of the event.

parameter

The parameter defined for the event.

Figure 18. The Raise Event panel

Raising an SAP event


Killing an SAP job instance

This section describes how to kill a Tivoli Workload Scheduler job that submits

either a standard SAP job or an SAP process chain.

Note: To perform this function on a Windows operating system, you must install

IBM Tivoli Workload Scheduler version 8.2.1 Fix Pack 1, or later.

To kill an SAP job instance, perform the following steps:

1. Run a list of job instances that contains the job that you want to kill.

2. Right-click the job instance and select Kill from the pop-up menu.

The Tivoli Workload Scheduler job status is set to ABEND. The SAP job or process

chain is set to canceled in the SAP system.

Note: If you kill a process chain job, the SAP system stops as soon as the process

that is currently running completes.



1

11

11

1

1

1

11

11



Chapter 17. Defining SAP jobs dynamically

When you launch a job created as described in “Defining a job that runs an SAP

job” on page 115 and “Task string to define SAP jobs” on page 129, Tivoli

Workload Scheduler makes a copy of the predefined job (also known as a template

job) and runs the copy. If you want to run the job on several SAP systems, you

need to manually create the template job on each system.

This chapter describes how to create and submit SAP jobs dynamically without

creating or referencing predefined job templates, by submitting:

v In the SAP system, a job that does not refer to an existing template in the SAP

R/3 database.

v A job that references a predefined job template stored in the SAP R/3 database

for which you want to change a parameter.

To take full advantage of this feature, make sure you have XBP version 2.0

installed, because earlier versions of XBP do not support the full set of print and

archive parameters, or provide a way to set the job class or the spool list recipient.

In this chapter:

v “Task string to define SAP jobs dynamically” on page 150 uses a syntax diagram

to show the complete library of job creation parameters and provides a detailed

explanation of each parameter.

v “Specifying job parameters using variable substitution” on page 160 explains

how to provide parameters at run time by using the variable substitution

feature.

v “Dynamically defining and updating SAP jobs: some examples” on page 160

shows examples of this feature.


1

111

Task string to define SAP jobs dynamically

This section describes the task string that controls the running of SAP jobs. You can

build an entire job definition by using the six main sections concerning SAP job

parameters. These sections are grouped in Table 38 on page 152 and are related to

the:

v Job

v Job steps

v Variants associated with the steps (for ABAP modules only)

v Spool list recipients associated with the job

v Flags associated with the job

v Tracing specifications for the job

To define and submit an SAP R/3 job dynamically, use the following syntax:


�� -job job_name

-i

job_ID

-id

-flag type=exec �

� -host

host_name

-ts

-sg

server_group �

� -client

source_client

-exec_client

target_client �

� -c

class_value

-s

starting_step_number �

� -bdc_job_status_failed

bdc_processing

-nobdc

-nobdcwait

�

�

�

-sStep_number

attribute_name

=attribute_value

�

� -vStep_number

variant_name

-vtxtStep_number

variant_description �



1111111111

� -vparStep_number

name=variant_value �

� -vselStep_number

name=

i

#operation#lowest

e

#highest

�

� -recipient

R/3_login_name

-rectype

recipient_type �

� -flag

reccp

recbl

-flag recex

-flag recnf �

� -flag

im

immed

-flag

enable_joblog

disable_joblog

�

� -flag

enable_spoollist

disable_spoollist

-flag

pc_launch

-debug �

� -tracelvl

1

2

3

-rfctrace

-rfc_client

rfc_logon_client ��

The following is an example of a definition for the SAPTEST job:

-job SAPTEST -C A -user MAESTRO -s1 program=BTCTEST -s1 type=A -s1 pr_release

-s2 report=BTCTEST -s2 variant=BVT –s2 type=A -flag type=exec

-vpar2 TESTNAME=test -vtxt2 Test

Table 38 on page 152 describes the parameters for the task string to define SAP

jobs dynamically.

Note: The parameter values are case sensitive.


Chapter 17. Defining SAP jobs dynamically 151

Table 38. Task string parameters for SAP jobs (dynamic definition)


JOB -job job_name The name of the job to be run. This parameter is

mandatory.

-i job_ID

-id job_ID

The unique SAP job ID. Specify this parameter if you are

submitting a job that refers to a predefined job template

stored in the SAP database for which you want to

change a parameter.

-user user_name The SAP user who owns the template job. Specify this

parameter if you want to create a copy of the template

job. To use this parameter, the target SAP system must

have only one job with the specified name for the

specified user.

This parameter has no effect if a job ID is specified in the

job definition.

-host host_name

-ts host_name

The name of SAP workstation where the job is to be run.

host_name has the format

hostname_SAPsystemname_SAPsystemnumber.

For example, the name of a host might be

amss80a0_gs7_90

These parameters are mutually exclusive with -sg.

-sg server_group The name of the SAP server group where the job is to be

run. Use this parameter to run the job on an application

server that belongs to the group. The server group must

exist on the SAP system, otherwise an error code is

returned and the job is not launched.

This parameter is case-sensitive and can be up to 20

characters. It is mutually exclusive with -host and -ts.

-client source_client The number that identifies the SAP client where the job

definition is to be found, regardless of the client number

defined by the r3client key in the options file. This

parameter has no effect if a job ID is specified in the job

definition.

-exec_client target_client The number that identifies the SAP client where the job

is to be run, regardless of the client number defined by

the r3client key in the options file. This parameter

requires that the client-dependent data (such as the user

name and report variants) exists on both the source and

target clients.

This parameter has no effect if a job ID is specified in the

job definition.

-rfc_client rfc_logon_client The number that identifies the SAP client to be used for

RFC logon. This value overwrites the value specified by

the r3client keyword in the corresponding r3batch

options file.

-c class_value The priority with which the job runs in the SAP system.


A High priority

B Medium priority

C Low priority. This is the default value.



11111

11

|

||||||

||

111111

11

|

|

Table 38. Task string parameters for SAP jobs (dynamic definition) (continued)


JOB -flag type=exec Specify this parameter to enable the dynamic definition

of the SAP job. This parameter is mandatory.

-bdc_job_status_failed bdc_processing How Tivoli Workload Scheduler sets the completion

status of a job running BDC sessions, according to a

possible BDC processing failure. The allowed values are:

n If at least n BDC sessions failed (where n is an

integer greater than 0), Tivoli Workload


failed.

all If all the BDC sessions failed, Tivoli Workload


failed.

ignore When all the BDC sessions complete, regardless

of their status, Tivoli Workload Scheduler sets

the job completion status as successful. This is

the default value.

If -nobdc or -nobdcwait is set, this option is ignored.

-nobdc-

-nobdcwait

Disables the BDC Wait option (enabled by default) to

have the job considered as completed even if not all its

BDC sessions have ended.

STEP -s starting_step_number The number of the starting step.

-sstep_number attribute_name=attribute_value The step number and its attributes, where:

step_number

The number of the step being defined. Each step is

identified by a sequential number (1, 2, 3, ...n) using

the step number.

attribute_name

The name of the attribute.

attribute_value

The value of the attribute. It is optional for some

attributes.

Attributes can be defined in any order, but cannot be

repeated for the same step. Attribute validation is

performed before the job is created in the SAP system. If

the validation fails, the Tivoli Workload Scheduler job

goes into the ABEND state. For a detailed description of

each attribute and its values, see “Defining attributes for

ABAP steps” on page 156 and “Defining attributes for

external programs and external commands steps” on

page 159.

For example, the following step (step 8) is an ABAP

module running the report "MYPGM" and has two

attributes, only one of which has a value.

-s8 type=A -s8 program=MYPGM

-s8 pr_cover="My title" -s8 pr_immed



111111111111111111

1



VARIANT1 -vstep_number name The variant name for the specified step number.

-vtxtstep_number variant_description The textual description of the variant, in the Tivoli

Workload Scheduler logon language (customizable with

the TWSXA_LANG option of r3batch). The maximum length

is 30 characters.

-vparstep_number name=value For ABAP modules only. The value for a variant

parameter for the specified step number. This parameter

is mandatory when creating a new variant. For a

complete list of the supported attributes for ABAP steps,

see “Defining attributes for ABAP steps” on page 156.

-vselstep_number

name=sign#operation#lowest[#highest]

For ABAP modules only. The value for a variant

selection option for the specified step number.

sign Sign of the operation. Possible values are:

I Include

E Exclude

operation


EQ Equals

NE Not equal to

BT Between

NB Not between

LT Less than

LE Less than or equal to

GT Greater than

GE Greater than or equal to

CP Contains pattern

NP Does not contain pattern

lowest Low value of the selection. You can use up to 45

characters.

highest High value of the selection. You can use up to

45 characters. This attribute is optional.For a complete list of the supported attributes for ABAP

steps, see “Defining attributes for ABAP steps” on page

156.





SPOOL -recipient name The login name of an SAP user.

-flag {recp|recbl} Specifies how the spool list is sent to the recipient.


recp The spool list is sent as a copy.

recbl The spool list is sent as a blind copy.

-flag recex Specifies that the spool list is sent as an express message

to the recipient.

-flag recnf Specifies that the recipient is not allowed to forward the

spool list.

-rectype type Specifies the recipient type. Possible values are:

blank SAP user (default value)

B SAP user

C Shared distribution list

D X.500 address

G Organization object/ID

H Organization unit

I SAP object

L Telex number

O SAP Office user

P Private distribution list

R SAP user in another SAP system

U Internet address

1 Other recipient type

FLAGS -flag im

-flag immed

Specifies to launch the job immediately, meaning that if


-flag enable_joblog

-flag disable_joblog

Enables or disables retrieval of the joblog.

-flag enable_spoollist

-flag disable_spoollist

Enables or disables retrieval of the spool lists of the job.

-flag pc_launch Specifies to launch child jobs that are in scheduled state.

ON The product launches child jobs that are in

scheduled state.

OFF The product does not launch child jobs that are

in scheduled state. This is the default value.Note: You can use this option only if you activated the

parent-child feature on the SAP system. On the XBP 2.0

SAP system you can activate this feature using the

INITXBP2 ABAP report

TRACING -debug Enables maximum trace level.

-tracelvl 1|2|3 Specifies the trace setting for the job. Possible values are:

1 Only error messages are written in the trace file.

This is the default.

2 Informational messages and warnings are also

written in the trace file.

3 A most verbose debug output is written in the

trace file.For more details, refer to Chapter 29, “Configuring the

tracing utility,” on page 247.

-rfctrace

trace

Enables RFC trace.



Notes:

1. The following rules apply when you create or update SAP jobs dynamically:

v To create or reference a variant within an ABAP step, you can use one of the

following equivalent syntaxes:

– -s1 Variant=Var1

– -s1 Parameter=Var1

– -v1 Var1v If a variant does not exist, it is created with the parameters specified in the

job definition statement. In this case, all the required attributes of the variant

must be given a value. You cannot create empty variants.

v If a variant is already present in the SAP system, its values are modified

according to the command line parameters. If the existing variant is an

extended one, a new instance of it is created with resolved placeholders and

updated counters. This new variant instance is then updated using the

values from the command line. Finally, the job step is run using this variant

instance.

v All changes to the variant values are permanent. That is, Tivoli Workload

Scheduler neither restores the old values of the variants, nor deletes the

variants created after the job is run. Tivoli Workload Scheduler does not

change the case of the variant values.

Defining attributes for ABAP steps

Table 39 shows a complete list of the supported attributes for ABAP step module

definition:

Table 39. Supported attributes for ABAP step definition

Attribute

name Synonym Description Required

type typ Specify the step type. Possible values are:

v A

v ABAP

The product performs a check for correct

attribute values prior to launching the job.

U

program Specify the ABAP program name. U

parameter Specify the ABAP variant name. U

user authcknam Specify the user of the step U

language lang Specify the step language

This attribute accepts language names in either

the ISO format (two characters, for example

DE, EN) or the R/3 format (one character, for

example D, E)

If this attribute is not specified, the login

language of the access method is used

(customize using the option XAMETH_LANG

in the r3batch option files)

The product performs a check for a valid

language prior to launching the job.

U

pr_dest printer

pdest

Print Parameter: Specify the Printer for the

output.



Table 39. Supported attributes for ABAP step definition (continued)

Attribute


pr_copies prcop Print Parameter: Specify the number of copies.

The value of this attribute must be numeric. A

corresponding check is performed prior to

launching the job.

pr_lines linct Print Parameter: Specify the page length.



launching the job.

pr_columns linsz Print Parameter: Specify the page width.



launching the job.

pr_auth prber Print Parameter: Authorization

pr_arcmode armod Print Parameter: Archiving mode

pr_sapbanner prsap Print Parameter: SAP cover page

pr_exp pexpi Print Parameter: Spool retention period

The value of this attribute must be a single

digit. A corresponding check is performed prior

to launching the job.

pr_recip prrec Print Parameter: Recipient

pr_spoolname plist Print Parameter: Name of spool request ¹

pr_format paart Print Parameter: Print formatting ¹

pr_dep prabt Print Parameter: Department on cover page ¹

pr_spoolds prdsn Print Parameter: Name of spool data set ¹

pr_spoolprio priot Print Parameter: Spool request priority ¹

pr_immed primm Print Parameter: Print immediately ²

pr_release prrel Print Parameter: Delete after printing ²

pr_banner prbig Print Parameter: Selection cover page ²

pr_newspool prnew Print Parameter: New spool request ¹ ²

pr_cover prtxt Print Parameter: Text for cover page ¹. If the

string contains spaces it must be enclosed

between single quotes.

pr_hostcover prunx Print Parameter: Host spool cover page ¹ .




'D' Prints the default host cover page.

al_sapobject sap_object SAP ArchiveLink: Object type of business object

al_object object SAP ArchiveLink: Document type

al_info info SAP ArchiveLink: Info field

al_id archiv_id SAP ArchiveLink: Target storage system ¹

al_doctype doc_type SAP ArchiveLink: Document class ¹

al_rpchost rpc_host SAP ArchiveLink: PRC host ¹



Table 39. Supported attributes for ABAP step definition (continued)

Attribute


al_rpcserv rpc_servic SAP ArchiveLink: RPC service / RFC

destination ¹

al_iface interface SAP ArchiveLink: Name of communication

connection component ¹

al_client mandant SAP ArchiveLink: Client ¹

al_report SAP ArchiveLink: Report name ¹

al_text arctext SAP ArchiveLink: Text information field ¹

al_date datum SAP ArchiveLink: Archiving date ¹

al_user arcuser SAP ArchiveLink: Data element for user ¹

al_printer SAP ArchiveLink: Target printer ¹

al_format formular SAP ArchiveLink: Output format ¹

al_path archivpath SAP ArchiveLink: Standard archive path ¹

al_protocol protokoll SAP ArchiveLink: Storage connection protocol ¹

al_version SAP ArchiveLink: Version number ¹

Notes:

1. This attribute is available for BC-XBP 2.0 and later

2. This attribute is a flag, that is, it does not have a value, for example: –s2

pr_release

Tivoli Workload Scheduler performs the following syntax validation on job

attributes:

v Only valid attributes are allowed

v Checks if a particular attribute requires a value

v The values of the following attributes are checked:

– type

– language

– pr_copies

– pr_lines

– pr_colums

Validation is performed before the job is created in the SAP system. If the

validation fails, the Tivoli Workload Scheduler job goes into the ABEND state.



Defining attributes for external programs and external

commands steps

Table 40 shows a complete list of the supported attributes for external programs

and external commands step definition.

Table 40. Supported attributes for external programs and external commands step definition

Attribute


type typ The step type can assume one of the following

values:

For external programs

v X

v EXTPGM

For external commands

v C

v EXTCMDBefore launching the job, the product performs a

check for correct attribute values.

U

report ABAP program name or name of the external

program or command.

U

parameter Parameters for the external program or

command.

user authcknam User of the step.

language lang Step language.

This attribute accepts language names in either

the ISO format (two characters, for example DE,

EN) or the R/3 format (one character, for

example D, E).

If this attribute is not specified, the login

language of the access method is used (customize

using the XAMETH_LANG option in the

r3batch option files).

The product performs a check for a valid

language prior to launching the job.

targethost xpgtgtsys Target host for the external program or

command. This name must be exactly the same

as the name shown in the External Operating

System Commands table in the SAP system

(transaction SM69).

os opsystem Operating system for the external command. This

name must be exactly the same as the name

shown in the External Operating System

Commands table in the SAP system (transaction

SM69).

termcntl waitforterm Control flag: whether an external command or

program is to be run synchronously. ²

tracecntl Control flag: whether SAP tracing level 3 is

activated for tracing SAPXPG, the program that

starts an external command or program. ¹ ²

Defining attributes for external programs and external commands steps


11111

1111111

1

1111111

1

Table 40. Supported attributes for external programs and external commands step

definition (continued)

Attribute


stdoutcntl Control flag: indicates whether standard output

from an external command or program is to be

written to the job log. ¹ ²

stderrcntl Control flag: indicates whether standard error

from an external command or program is to be

written to the job log. ¹ ²

Notes:

1. This attribute is available for BC-XBP 2.0 and later

2. This attribute is a flag, that is, it does not have a value, for example: –s2

pr_release

Tivoli Workload Scheduler performs the following syntax validation on job

attributes:

v Only valid attributes are allowed

v Checks if a particular attribute requires a value

v The values of the following attributes are checked:

– type

– language

– pr_copies

– pr_lines

– pr_colums

Validation is performed before the job is created in the SAP system. If the

validation fails, the Tivoli Workload Scheduler job goes into the ABEND state.

Specifying job parameters using variable substitution

Parameters can be provided at run time using the variable substitution feature. For

example, the value appears as:

-s1 report=&VARNAME

The variable substitution process occurs while Tivoli Workload Scheduler is

creating the symphony file.

Dynamically defining and updating SAP jobs: some examples

This section describes some usage examples of this feature:

Job definition and run scenario using the -flag type=exec parameter

The following example creates and runs a 3-step job assigned to the user

MAESTRO. The first step runs the ABAP MYPROG1 using variant VAR01

and associated variant parameter. Step 2 has a step user defined. Step 3

uses the same ABAP as step 1 with no associated variant.

The only requirement is that the elements referred to are known in the

SAP system (user, program). If the variant does not exist, there should be a

set of values to define the content of the variant for its creation (pairs of

–vpar<N> -vsel<N> parameters for the parameters and selections of the

ABAP program).

Defining attributes for external programs and external commands steps


-job TESTJOB01 –user MAESTRO –c A

-s1 type=A –s1 program=MYPROG1–v1 VAR01 –vpar1 TESTNAME=TST

-s2 report=SPOOLX1 –s2 user=PRTUSER

–s3 type=A –s3 program=MYPROG1 –flag type=exec

The job returns job ID 12345678

Job copy and overwrite the job created in the previous step

The following job statement references the job created in the previous

example. A new copy of the job is made and the parameters specified in

the invocation are used to update the definition. In this case the variant for

step 1 is modified and a new external program step (Step 4) is added.

-job TESTJOB01 –i 12345678 –s1 variant=VAR01A –vpar1

TESTNAME=TST2

–s4 type=X -s4 report=niping –s4 parameter=-t -flag type=exec

Copy and overwrite a job referencing an existing job template

The following example shows a job creation referencing a job template

(previously created without using this feature). A template job called

TEMPLAJOB already exists on the SAP system with an ID of 56780123. It

is a single ABAP step job to which we now add some print parameters.

-job TEMPLAJOB

–I 56780123 -s1 pr_immed -flag type=exec

Dynamically defining and updating SAP jobs: examples


Dynamically defining and updating SAP jobs: examples


Chapter 18. Using Business Information Warehouse

Business Information Warehouse (BIW) is a data warehouse solution tailored to

SAP R/3. It allows business reporting and decision support.

To use the InfoPackages component, you must have the SAP Business Warehouse

Systems, version 2.0B or higher installed.

To use the Process Chains component, you must have the SAP Business Warehouse

Systems, version 3.0B or higher installed.

The Support Package 9 (SAPKW31009) for SAP Business Warehouse 3.1 is required

so that r3batch 8.3 can launch Process Chains.

This chapter provides information about:

v “Business Warehouse components”

v “Defining user authorizations to manage SAP R/3 Business Warehouse

InfoPackages and process chains” on page 164

v “Managing SAP R/3 Business Warehouse InfoPackages and process chains” on

page 164

Business Warehouse components

SAP R/3 supports two main Business Warehouse components, InfoPackages and

Process Chains.

An InfoPackage is the entry point for the loading process from a specific

InfoSource (a logical container of data source, generically named InfoObject).

Technically, an InfoPackage is an SAP R/3 job whose aim is to load data. Like any

other SAP R/3 job, it contains job specific parameters such as start time, and

dependencies.

A Process Chain is a complex chain of different processes and their relationships.

The processes within a process chain are not limited to data load processes, or

InfoPackages, but also include:

v Attribute/Hierarchy Change run

v Aggregate rollup

v ABAP program

v Another process chain

v Customer build process


Defining user authorizations to manage SAP R/3 Business Warehouse

InfoPackages and process chains

Tivoli Workload Scheduler for Applications for SAP can manage SAP R/3 Business

Warehouse InfoPackages and process chains. To use the SAP R/3 Business

Warehouse functions, you must define a Tivoli Workload Scheduler user within

SAP R/3 with full authorization for the ABAP Workbench object S_DEVELOP.

The user must also belong to the following profiles:

v S_BI-WHM_RFC (for Business Information Warehouse version 7.0, or later)

v S_RS_ALL

v Z_MAESTRO

Managing SAP R/3 Business Warehouse InfoPackages and process

chains

Business Warehouse InfoPackages and process chains can only be created from the

SAP R/3 environment. However, since feature level 1.3, the Job Scheduling

Console supports pick lists of InfoPackages and process chains, so that you can

also define Tivoli Workload Scheduler extended agent jobs for these objects.

This section describes how to perform the following tasks on the SAP R/3 Business

Warehouse InfoPackages and process chains:

v “Creating a Tivoli Workload Scheduler job that contains InfoPackages or process

chains”

v “Displaying details about Business Warehouse InfoPackages” on page 169

v “Task string to define Business Warehouse InfoPackages and process chains” on

page 169

v “Mapping between Tivoli Workload Scheduler and SAP job states” on page 145

Creating a Tivoli Workload Scheduler job that contains

InfoPackages or process chains

This section describes how to create a Tivoli Workload Scheduler job that contains

a Business Warehouse InfoPackage or a process chain.

To be able to schedule InfoPackages using Tivoli Workload Scheduler, the

scheduling options of the InfoPackage must have:

v Start type set to Start later in background process.

v Start time set to immediate.

To create a Tivoli Workload Scheduler job definition that contains an InfoPackage

or process chain in the Tivoli Workload Scheduler database, perform the following

steps:


Definition.


Defining user authorizations to manage InfoPackages and process chains





General page




Task Type

Select SAP.

Name

Type the name of the IBM Tivoli Workload Scheduler job. The name must

start with a letter, and can contain alphanumeric characters, dashes, and

underscores. The maximum length is 40 characters.

Workstation Name

Type the name of the SAP R/3 workstation where the IBM Tivoli Workload

Scheduler job runs or use ellipsis (...) to display a list of SAP R/3

workstations.

Figure 19. The General page of the Properties - Job Definition panel

Creating Tivoli Workload Scheduler job with InfoPackages or process chains

Chapter 18. Using Business Information Warehouse 165

Description

Type a description of the IBM Tivoli Workload Scheduler job. The maximum

length is 120 characters.v Login group:

Login Type the name of the user who launches the IBM Tivoli Workload

Scheduler job. The maximum length is 47 characters. Specify a user who

can log on to the workstation where the job runs.v Recovery Options group:

Select the recovery option you want to associate with the IBM Tivoli Workload

Scheduler job if it ends in error. Possible values are:

– Stop. Do not continue with the next job. This is the default value.

– Continue. Continue with the next job.

– Rerun. Rerun the job.

Message






Job

Click ellipsis (...) to display a list of recovery jobs from where to select the

recovery job to run if the parent job ends in error. Recovery jobs are run only

once for each instance of the parent job ended in error.

Workstation Name








job workstation.


Status mode.

Task page

Use the Task page to provide task information for the Tivoli Workload Scheduler

job.


Task Type

This information field indicates that the job is SAP R/3 task type. The task type

depends on the SAP R/3 system where you defined the job.v R/3 Job Type group:

R/3 Job Type

Select Business Warehouse InfoPackage or Business Warehouse Process

Chain.v R/3 Job Identity group:



Job Name

Type the SAP R/3 job name or use ellipsis (...). The SAP Pick List panel is

displayed.

Business Warehouse InfoPackages:

The SAP Pick List panel.

Click Start to get a complete list of existing InfoPackages or filter your

query by filling in one or more of the following fields:

Name & Location group:

Find Specify an SAP R/3 InfoPackage name. You can use the

wildcard asterisk (*). The search tool lists all the InfoPackages

having this name. The list is displayed in the language set in

the twsxa_lang option. If you use asterisks and specify an

information in the Advanced Filter group fields the search

tool displays:

– The information you specified if contained in the SAP R/3

database.

– All the information contained in the SAP R/3 database if

the information you specified does not exist.

Advanced Filter group:

Click Advanced Filter and specify one or more of the following items

of information. You cannot use the wildcard asterisk (*).

InfoSource

The structure that consists of InfoObjects and is used as a

non-persistent store to connect two transformations.

DataSource

The object that makes data for a business unit available to Business

Figure 20. The SAP Pick List panel



Information Warehouse. A DataSource contains a number of

logically-related fields that are arranged in a flat structure and

contain data to be transferred into Business Information

Warehouse.

SourceSystem

The system that is available to Business Information Warehouse for

data extraction and transfer purposes.

Note: If you specify any information that does not exist, the search

tool lists all the information contained in the SAP R/3 database.

Business Warehouse Process Chains:

The SAP Pick List panel

Click Start to get a complete list of existing Process Chains or filter your

query by filling in one or more of the following fields:

Name & Location group:

Find Specify an SAP R/3 process chain. You can also use asterisks

(*). The search tool lists all the process chains having this

name.

Technical Name

Specify the name that identifies the process chain. The search

tool lists all the SAP R/3 process chains having this technical

name.

Job ID

Displays the job identifier assigned by the SAP R/3 system. Possible values

are:

ipak_ For Infopackges

pchain_ For Process Chainsv Debug and Setting Options group:

Trace Select to create a trace file dev_rfc in the Tivoli Workload Scheduler

home directory. Ensure you delete the trace option from the job after you

have performed debug procedures. The dev_rfc file can become very

large and cause problems to your system.

Figure 21. The SAP Pick List panel



Debug

Select to include additional debug information in the stdlist file of the

job.v R3 Command Line group:

R3 Command Line

Type any flags that are valid for the SAP R/3 command line, such as the

following for process chains:

-flag level_all_pchainlog -flag pchainlog_chains_only

-flag enable_pchainlog_bapi_msg

and the following for InfoPackages:

-flag enable_ipaklog

v Job Options group:

PChain Log (for job process chain only)

Select it to retrieve the job process chain log. Possible values are:

– Blank

– Enabled

– Disabledv Return Code Mapping group:

Expression

Type a logical expression that defines the success condition. Allowed

operators are comparison operators (=, != or <>, >, >=, <, <=) and logical

operators (AND, OR, NOT). For example, the expression RC>= 6 indicates

that a return code greater than or equal to 6 means the task is successful.

Displaying details about Business Warehouse InfoPackages

To display details about a Business Warehouse Info Package, perform the following

steps:

1. In the Work with engines pane, select an engine → database list → job definition list.

The list of job pane displays the available jobs.

2. Double-click the SAP R/3 job whose details you want to display. The Properties

- Job Definition panel is displayed.



v “Task page” on page 1663. In the Task page, click Details. The Details panel is displayed. It contains all

the information relevant for the job.


5. Click OK.

Task string to define Business Warehouse InfoPackages and

process chains

This section describes the task string parameters that control the running of the

Business Warehouse InfoPackages and process chains jobs. You must specify them

in the following places when you define their associated Tivoli Workload

Scheduler jobs:

v If you use the Job Scheduling Console, in the Command field of the Task page

of the Properties - Job Definition panel. You must select Other as task type and

not SAP for the new job definition.







environment.

The string syntax is the following:


�� -job job_name -i ipak_

pchain_

-debug

-trace �

� -flag

imm

immed

-flag

enable_pchainlog

disable_pchainlog

�

� -flag

enable_ipaklog

disable_ipaklog

-flag

level_all_pchainlog

level_n_pchainlog

�

� -flag

pchainlog_chains_only

pchainlog_chains_and_failed_proc

pchainlog_complete

�

� -flag

enable_pchainlog_bapi_msg

disable_pchainlog_bapi_msg

�

� -flag

enable_pchain_details

disable_pchain_details

-flag

pchain_rerun

pchain_restart

pchain_refresh

��

The parameters are described in Table 35.

Table 41. Task string parameters for SAP R/3 jobs

Parameter Description GUI

Support

-job job_name The name of the task to be run. It is either an

InfoPackage technical field name, or a process chain

name. This parameter is mandatory.

U

-i {ipak_ | pchain_} One of the following:

ipak_ Target job is an InfoPackage

pchain_ Target job is a process chain

U

-debug Turns on the most verbose r3batch trace. This option

is for debugging the extended agent and should not be

used in standard production.

U

Task string to define InfoPackages and process chain jobs


1111111

Table 41. Task string parameters for SAP R/3 jobs (continued)


Support

-trace Turns on the SAP RFC trace.

When you use this option, a trace file is created in the

Tivoli Workload Scheduler methods directory. In UNIX,

this trace file is called dev_rfc. In Windows, the file is

called rfcxxxxx_xxxxx.trc.

This option is for debugging the extended agent and

should not be used in standard production. Ensure

you delete the trace option from the job after you have

performed debug procedures. The trace file can

become very large and unmanageable.

U

-flag {imm | immed} Specifies to launch job immediately, meaning that if


U

-flag {enable_pchainlog | disable_pchainlog} Enables or disables retrieval and appending of the

process chain job log in the Tivoli Workload Scheduler

stdlist. Disable if the size of the log affects

performance. A related configuration option can be set

for this purpose at a more general level. See Table 33

on page 106.

U

-flag {enable_ipaklog | disable_ipaklog} Enables or disables retrieval and appending of the

InfoPackage job log in the Tivoli Workload Scheduler

stdlist. Disable if the size of the log affects

performance. A related configuration option can be set

for this purpose at a more general level. See Table 33

on page 106.

-flag {level_n_pchainlog | level_all_pchainlog} Allows for retrieval of process chain logs down to the

process chain level you specify.

level_n_pchainlog

Specifies that the process chains are logged down

to, and including, the level represented by number

n.

level_all_pchainlog

Specifies that all the process chains are logged.

The default is level_1_pchainlog.

A related configuration option can be set for this

purpose at a more general level. See Table 33 on page

106.



Table 41. Task string parameters for SAP R/3 jobs (continued)


Support

-flag {pchainlog_chains_only |

pchainlog_chains_and_failed_proc |

pchainlog_complete}

Specifies what type of process chain-related logs will

be retrieved.

pchainlog_chains_only

Only the process chains are logged.

pchainlog_chains_and_failed_proc

In addition to the process chains, all the processes

that failed are also logged.

pchainlog_complete

The process chains and all processes are logged.

The default is pchainlog_complete.

A related configuration option can be set for this

purpose at a more general level. See Table 33 on page

106.

-flag {enable_pchainlog_bapi_msg |

disable_pchainlog_bapi_msg}

Enables or disables retrieval of additional messages

from the BAPI calls from the SAP Business Warehouse

process chains and appends them to the Tivoli

Workload Scheduler stdlist.

-flag {enable_pchain_details |

disable_pchain_details}

Enables or disables the display of details about the

process chain job. A related configuration option can

be set for this purpose at a more general level. See


U

-flag {pchain_rerun | pchain_restart |

pchain_refresh}

Determines the action that Tivoli Workload Scheduler

performs when you rerun a job that submits a process

chain.

pchain_rerun

Tivoli Workload Scheduler creates another process

chain instance and submits it to be run again.

pchain_restart

Tivoli Workload Scheduler restarts the original

process chain from the failing processes to the end.

pchain_refresh

Tivoli Workload Scheduler updates the status and

details of the original process chain.

For more details about rerunning a process chain, refer

to “Rerunning a process chain job” on page 138.

U

Note: Typically, the -debug and -trace options are for debugging the extended

agent and should not be used in standard production.

The following is an example for an InfoPackage job whose technical field name is

ZPAK_3LZ3JRF29AJDQM65ZJBJF5OMY:

-job ZPAK_3LZ3JRF29AJDQM65ZJBJF5OMY -i ipak_



111111

1

11111111111111

11

1

Chapter 19. Using the BDC Wait option

With the Batch Data Collector (BDC) Wait option, you can specify that an R/3 job

launched by Tivoli Workload Scheduler is not to be considered complete until all

of its BDC sessions have completed. This prevents other Tivoli Workload Scheduler

jobs that are dependent on the R/3 job from being launched until all of the related

BDC sessions for the R/3 job have ended.

To make use of the option, an R/3 job must write informational messages in its job

log. This can be done by modifying the SAP function module BDC_OPEN_GROUP

as follows:

FUNCTION BDC_OPEN_GROUP.

...

CALL ’BDC_OPEN_GROUP’ ID ’CLIENT’ FIELD CLIENT

ID ’GROUP’ FIELD GROUP

ID ’USER’ FIELD USER

ID ’KEEP’ FIELD KEEP

ID ’HOLDDATE’ FIELD HOLDDATE

ID ’DESTINATION’ FIELD DEST

ID ’QID’ FIELD QID

ID ’RECORD’ FIELD RECORD

ID ’PROG’ FIELD PROG.

*

IF SY-SUBRC EQ 0.

BQID = QID.

BUSER = SY-MSGV1.

BGROUP = GROUP.

* CALL FUNCTION ’DB_COMMIT’.

CALL FUNCTION ’ENQUEUE_BDC_QID’

EXPORTING DATATYP = ’BDC ’

GROUPID = BGROUP

QID = BQID

EXCEPTIONS FOREIGN_LOCK = 98

SYSTEM_FAILURE = 99.

IF SY-SUBRC EQ 0.

message i368(00) with ’BDCWAIT: ’ qid.

ENDIF.

ENDIF.

*

PERFORM FEHLER_BEHANDLUNG USING SY-SUBRC.

*

*

ENDFUNCTION.

Note: The actual parameters of the call of the C function (CALL ‘BDC_OPEN_GROUP’

ID ...) might vary depending on the SAP release. With this approach, you

obtain a global change in your R/3 system.

The completion status of an R/3 job launched by Tivoli Workload Scheduler is

based on the value you set for the bdc_job_status_failed option. By default, this

option is set to ignore, meaning that the job is considered successfully completed

when the BDC sessions are finished, regardless of their success or failure. For

details about the bdc_job_status_failed option, refer to Table 35 on page 131.


11111


Chapter 20. Job interception and parent-child features

This chapter describes how the job interception and parent-child features of

BC-XBP 2.0 are supported by Tivoli Workload Scheduler for Applications.

Job interception

Job interception is a feature of the BC-XBP 2.0 interface. It enables Tivoli Workload

Scheduler to have a very sophisticated control over the jobs launched by SAP R/3

users from the SAP graphical interface.

The job interception mechanism becomes active when the SAP R/3 job scheduler is

about to start an SAP R/3 job (that is, when the start conditions of an SAP R/3

job are fulfilled). It checks the job parameters (job name, creator, client) against

the entries in the SAP R/3 table TBCICPT1, and when the job parameters match the

criteria, the SAP R/3 job is set back to the scheduled status and is marked with a

special flag, denoting that the job has been intercepted.

If Tivoli Workload Scheduler has been set up to handle job interception, it

periodically runs its own job to retrieve a list of intercepted jobs and reschedules

them. This job can be referred to as the interception collector job.

Implement the following steps to set up Tivoli Workload Scheduler to handle job

interception in an SAP R/3 environment:

1. Install the BC-XBP 2.0 interface.

2. Activate the job interception feature of the BC-XBP 2.0 interface.

3. Define a Tivoli Workload Scheduler job to periodically collect the intercepted

SAP R/3 jobs.

4. Specify interception criteria in the SAP R/3 system.

5. Specify interception criteria in Tivoli Workload Scheduler.

Note: Jobs launched by Tivoli Workload Scheduler, or by any other external

scheduler using the BC-XBP interface, cannot be intercepted. This is due to

the design of the interception mechanism, which only considers jobs whose

start conditions have been fulfilled due to time or SAP event restrictions.

Implementing job interception

This section describes what action you need to take to implement job interception.

Activating the job interception feature

Refer to SAP note 604496 to know if your SAP R/3 system already has the BC-XBP

2.0 interface, or which SAP R/3 support package you need to install to enable it.

To enable the job interception feature, run ABAP report INITXBP2. This report

shows you the current status of the job interception and parent-child features, and

allows you to toggle the status of both features.

Collecting intercepted jobs periodically

Because intercepted jobs remain in the scheduled status until they are re-launched,

you need to define a Tivoli Workload Scheduler job that uses the SAP R/3

interception collector task to collect and restart them.


To define a Tivoli Workload Scheduler job that intercept jobs in scheduled status,

use the following syntax:

CPUNAME#JOBNAME

SCRIPTNAME "TWShome/methods/r3batch -t HIJ -c CPUNAME"

DESCRIPTION "Collects intercepted jobs on SAP XA CPUNAME"

STREAMLOGON TWSuser

RECOVERY STOP

CPUNAME The name of the extended agent workstation.

JOBNAME The name of the Tivoli Workload Scheduler job.

TWShome The fully qualified path to your Tivoli Workload Scheduler

installation.

–t HIJ The SAP R/3 task type to intercept jobs in scheduled status. HIJ

stands for Handle Intercepted Jobs.

TWSuser The name of the Tivoli Workload Scheduler user that launches the

access method.

The incerception collector job runs at periodical intervals; for example, every 10

minutes. It retrieves all the jobs that have been intercepted since the last run of the

interception collector, and launches them again according to a template.

Setting interception criteria on the SAP R/3 system

On SAP R/3, the interception criteria are held in table TBCICPT1. Only jobs that

match the criteria of this table are intercepted, when their start conditions are

fulfilled. All the other jobs are run normally.

You can maintain the entries in this table by using transaction se16 and setting the

following:

v Client number

v Job mask

v User mask

Setting interception criteria on Tivoli Workload Scheduler

In Tivoli Workload Scheduler, interception criteria are defined and used by setting:

Table criteria

For details about how you set table criteria, see “Setting SAP R/3 table criteria

using the Job Scheduling Console.”

Template files (optional)

For details about how you create template files, see “Using template files” on

page 177.

You can set these using the Job Scheduling Console.

Setting SAP R/3 table criteria using the Job Scheduling Console

To set table criteria on an SAP R/3 job using the Job Scheduling Console, perform


1. In the Work with engines pane, select an engine → database list → job definition list.

The list of job pane displays the available jobs.

2. Right-click the job and select Table Criteria.

The Table Criteria panel opens.

Collecting intercepted jobs periodically



Client

The client workstation of the SAP R/3 job.

Job Name

Specify a filter to match a set of SAP R/3 jobs. Use the * (asterisk) to match

a set of jobs.

Job Creator

Specify a filter to match a set of SAP R/3 job creator. Use the * (asterisk) to

match a set of jobs.

Job Template

Optionally, specify the template file that contains instructions for the

interception collector about how to run the intercepted SAP R/3 job under

control of Tivoli Workload Scheduler. For more information about template

files, see “Using template files.”3. Perform one of the following actions:

Add To add a new interception criteria.

Delete To delete a new interception criteria.

Select a row To modify an interception criteria.4. Click OK.

Using template files: A template is a file with extension .jdf located in the same

directory as the interception criteria file (TWShome/methods/r3batch_icp). The

template file contains instructions for the interception collector about how to run

Figure 22. The Table Criteria panel

Setting SAP R/3 table criteria

Chapter 20. Job interception and parent-child features 177

|||||

|||

the intercepted SAP R/3 job under control of Tivoli Workload Scheduler. Its syntax

corresponds to the syntax of docommand in conman. You can use any text editor to

maintain this file.

If the user template file is empty, a template file named default.jdf is used. If

default.jdf does not exist, the following instructions are used:

alias=SAP_$RUN_$JOBNAME_$JOBCOUNT

This means that the intercepted SAP R/3 jobs are to be restarted immediately, due

to the absence of the at= job option. Their Tivoli Workload Scheduler names are

composed of the string SAP_, the current run number of the interception collector,

and the name and ID of the SAP R/3 job.

Thus, the instruction set for restarting an intercepted SAP R/3 job is retrieved in

the following order:

1. From the template file, if an existing template is specified in the interception

criteria file.

2. From the default template file, if the template is specified in the interception

criteria file but does not exist, or if the template is not specified in the

interception criteria file.

3. From the default instruction set, if the default template file does not exist.

Job interception example: The interception criteria table on SAP R/3 contains the

following entry:

The interception criteria file in Tivoli Workload Scheduler contains the following

entry:




|

|||

|||

||

|

||||

||

||

|||

|

|||

|||

The template file at1700.jdf contains the following entry:

alias;at=1700

This implies that all jobs, started in client 000 by SAP R/3 users whose user name

begins with fa, will be intercepted. The interception collector restarts the jobs using

the instructions from the template file at1700.jdf. The SAP R/3 jobs are restarted

at 17:00 with a random name, due to the alias command.

Using placeholders: In the template files you can use a number of placeholders

that are replaced by the interception collector at run time. They are listed in

Table 42.

Table 42. Placeholders for job interception template files

Placeholder Description

$CPU Name of the extended agent workstation on which the

interception collector runs.

$CLIENT Client number of the intercepted SAP R/3 job.

$JOBNAME Name of the intercepted SAP R/3 job.

$JOBCOUNT Job ID of the intercepted SAP R/3 job.

$USER Name of the user who launched the SAP R/3 job.

$JOBNUM Job number of the interception collector.

$RUN Current run number of the interception collector.

$SCHED Schedule name of the interception collector.

$RAND Random number.

Thus, the template:

alias=ICP_$RAND_$JOBNAME_$JOBCOUNT_$CLIENT;at=1000



Chapter 20. Job interception and parent-child features 179

|

||||

|

||||

|||

||

||

|||

||

||

||

||

||

||

||

|||

|

|

instructs the interception collector to restart the SAP R/3 job named DEMO_JOB with

job ID 12345678 on client 100 at 10:00 as Tivoli Workload Scheduler job

ICP_1432_DEMO_JOB_12345678_100.

The parent-child feature

In some situations, an SAP R/3 job dynamically spawns a number of other jobs;

for example, to distribute the workload to the free application servers. Prominent

examples are the mass activity jobs of the SAP R/3 FI-CA component. Before

BC-XBP 2.0, it was difficult for external schedulers to handle this situation, because

the business process does not usually end with the termination of the initial job

(parent job), but with the termination of all subjobs (child jobs).

The BC-XBP 2.0 interface allows you to determine whether a job has launched

subjobs, together with their names and IDs, and so it is now possible to track

them.

To activate this feature, use the INITXBP2 ABAP report, which you can also use to

toggle the status of job interception.

When the parent-child feature is active, Tivoli Workload Scheduler considers an

SAP R/3 job as finished only after all its child jobs have terminated. The status of

the Tivoli Workload Scheduler job remains as EXEC while the parent job or any of

its child jobs are running.

The status of the Tivoli Workload Scheduler job becomes SUCC if the parent job and

all child jobs terminate successfully. If any of the jobs terminated with an error, the

status of the Tivoli Workload Scheduler job becomes ABEND.

Note: The parent-child feature can interfere with job interception because,

although the parent job cannot be intercepted, any of its child jobs can be

intercepted if they match the interception criteria. In this case, the Tivoli

Workload Scheduler job remains in the EXEC status until the intercepted

child job has been relaunched and has terminated.

The joblogs of the child jobs are appended in the Tivoli Workload Scheduler

stdlist after the joblog of the parent job.



|||

Chapter 21. Exporting SAP R/3 factory calendars

This chapter describes how to export SAP R/3 factory calendars into a file whose

format can be processed by the Tivoli Workload Scheduler composer command

line, to add the exported calendar definitions to the Tivoli Workload Scheduler

database.

Business scenario

You might want to configure your Tivoli Workload Scheduler scheduling activities

based on the schedule calendar in your SAP R/3 system. To do this, use the

r3batch export function to export the SAP R/3 calendar definitions into a file

whose format is compatible with the Tivoli Workload Scheduler composer

command line. Based on the parameters you specify, you create a file that contains

only the SAP R/3 calendar definitions that meet your scheduling requirements.

Use this file as input for the composer add command, to import the calendar

definitions into the Tivoli Workload Scheduler database. Your Tivoli Workload

Scheduler and SAP R/3 calendars are now synchronized.

To keep the Tivoli Workload Scheduler and SAP R/3 calendar definitions

synchronized and avoid duplicating data maintenance in the two environments,

you can schedule to export the calendar definitions from SAP R/3 and import

them to Tivoli Workload Scheduler on a regular basis using a dedicated job.

Using the r3batch export function

Use the export function to access and download factory calendars that are

available in an SAP R/3 system. The main purpose of this export function is to

create an output file that can be used by the composer to synchronize Tivoli

Workload Scheduler calendars with existing SAP R/3 factory calendars, integrating

the calendar definitions from SAP R/3 into Tivoli Workload Scheduler.

For details about the Tivoli Workload Scheduler calendar definitions, refer to the


To export an SAP R/3 calendar, from twshome/methods (where twshome is the

complete path where you installed Tivoli Workload Scheduler) enter the following

command:

Command syntax

�� -r3batch -t RSC -c cpu_name -- ″ -calendar_ID calendarID �

�

-year_from

yyyy

-year_to

yyyy -getworkdays

-getfreedays

�

� -tws_name

tws_cal_name

-tws_description

tws_cal_desc �


|

|

||||

||

|||||||||

||||

||

|||||

||

|||

|

||||||||||||||||

|||||||||||||||||||||||

|||||||||||||||||||||||

||

� -filename

output_filename ″ ��

Where:

-t RSC

The identifier of the task to be performed, in this case RSC (Retrieve SAP R/3

Calendars). This parameter is required.

-c cpu_name

The CPU name of the SAP R/3 system where the calendar data to export

resides. The SAP R/3 system must be configured as a workstation to Tivoli

Workload Scheduler. This parameter is required.

-calendar_id calendarID

The identifier of the SAP R/3 calendar to be exported, which consists of two

alphanumeric characters. This parameter is required.

-year_from yyyy

The year of the calendar from when to start exporting dates, in the format yyyy.

This parameter is required.

-year_to yyyy

The year of the calendar when to stop exporting dates, in the format yyyy. This

parameter is required.

-getworkdays | -getfreedays

Specify getworkdays to create the Tivoli Workload Scheduler calendar

definition based on the working days of the SAP R/3 calendar. In this way,

each date of a working day is stored in the output file.

Specify getfreedays to create the Tivoli Workload Scheduler calendar definition

based on the holidays of the SAP R/3 calendar. Each date of a non-working

day is stored in the output file.

These parameters are optional and mutually exclusive. If you do not specify

either, the default is getworkdays.

-tws_name tws_cal_name

The Tivoli Workload Scheduler name for the exported SAP R/3 factory

calendar. It is stored in the output file.

You can specify up to eight alphanumeric characters. This parameter is

optional, the default is SAPXX_calendarID, where:

XX Corresponds to WK if the calendar includes only working days

or FR if the calendar includes only non-working days.

calendarID The identifier of the SAP R/3 calendar.

For example, the default Tivoli Workload Scheduler name for an exported

calendar, whose identifier is 04, that includes only working days, is SAPWK_04.

-tws_description tws_cal_desc

The description of the Tivoli Workload Scheduler calendar. It is stored in the

output file. You can specify up to 120 alphanumeric characters. If the

description contains blanks, it must be enclosed between single quotes. This

parameter is optional.

-filename output_filename

The name of the output file that is to contain the calendar definitions. This file

is written in a scheduling language that can be processed by the composer

when you add the calendar data to the Tivoli Workload Scheduler database.

Using r3batch export function


||||||||||||||||

||

|||

||||

|||

|||

|||

||||

|||

||

|||

||

|||

||

||

|||||

||||

You can specify a file name with its complete or partial path; if you do not

specify any path, the file is created in the current directory. If the path you

specify does not exist, it is created, provided that you have the appropriate

access rights. Otherwise, the command returns an error message and is not

performed.

You can specify up to the maximum characters allowed by your operating

system. If the name of the file contains blanks, it must be enclosed between

single quotes. If another file with the same name exists, it is overwritten.

This parameter is optional. The default value is tws_name.txt, where tws_name is

the value you set for the tws_name parameter.

The following is an example of an SAP R/3 factory calendar export command:

r3batch -t RSC -c tivoli10 -- " -calendar_id 01 -year_from 2007 -year_to 2010

-tws_name TWS_CAL1 -tws_description ’TWS SAP Calendar 01’ -getworkdays

-filename ’my dir/tws_calendar_01.dat’ "

This command exports the SAP R/3 calendar named 01, that resides on the SAP

R/3 system named tivoli10. The dates exported begin from year 2007, until year

2010, considering only working days. The Tivoli Workload Scheduler name used

for the calendar is TWS_CAL1, and the description written in the output file is

TWS SAP Calendar 01. The output file is named tws_calendar_01.dat, stored in

twshome/methods/my dir, and its content looks like the following:

$CALENDAR

TWS_CAL1

"TWS SAP Calendar 01"

01/02/2007 01/03/2007 01/04/2007 01/05/2007 01/08/2007 01/09/2007 01/10/2007

01/11/2007 01/12/2007 01/15/2007 01/16/2007 01/17/2007 01/18/2007 01/19/2007

01/22/2007 01/23/2007 01/24/2007 01/25/2007 01/26/2007 01/29/2007 01/30/2007

01/31/2007 02/01/2007 02/02/2007 02/05/2007 02/06/2007 02/07/2007 02/08/2007

.......

11/24/2010 11/25/2010 11/26/2010 11/29/2010 11/30/2010 12/01/2010 12/02/2010

12/03/2010 12/06/2010 12/07/2010 12/08/2010 12/09/2010 12/10/2010 12/13/2010

12/14/2010 12/15/2010 12/16/2010 12/17/2010 12/20/2010 12/21/2010 12/22/2010

12/23/2010 12/24/2010 12/27/2010 12/28/2010 12/29/2010 12/30/2010 12/31/2010

To import the exported calendar definitions into the Tivoli Workload Scheduler

database, copy the output file from the extended agent for SAP R/3 to the master

workstation and from the composer command line on the master workstation,

enter the following command:

-add output_filename

where ouput_filename is the name of the exported file, with its complete path.

For example, to import the tws_calendar_01.dat file exported in the previous

example, copy the file to the master workstation. From the composer command

line on the master workstation, enter:

-add twshome/methods/my dir/tws_calendar_01.dat

where twshome is the complete path where you installed Tivoli Workload Scheduler.

Using r3batch export function

Chapter 21. Exporting SAP R/3 factory calendars 183

|||||

|||

||

|

|||

||||||

||||||||||||

||||

|

|

|||

|

|


Chapter 22. Defining internetwork dependencies and event

rules based on SAP R/3 events

This chapter describes how to define internetwork dependencies and event rules

for Tivoli Workload Scheduler based on SAP events. It contains the following

sections:

v “Defining internetwork dependencies based on SAP events”

v “Defining internetwork dependencies based on SAP events with the Job

Scheduling Console” on page 188

v “Defining event rules based on SAP events” on page 189

v “Monitoring SAP events” on page 190

Defining internetwork dependencies based on SAP events

Dependencies are prerequisites that must be satisfied before a job or job stream can

start. Internetwork dependencies are dependencies checked by the extended agent

workstation to which they belong. In response to an internetwork dependency, the

SAP extended agent checks for the occurrence of the SAP event specified in the

dependency. As soon as the SAP event is raised, the SAP extended agent commits

the event and instructs Tivoli Workload Scheduler to resolve the corresponding

internetwork dependency.

For more details about internetwork dependencies, refer to the Tivoli Workload

Scheduler Reference Guide. For more details about how to raise SAP events, see

“Raising an SAP event” on page 145.

To define SAP events as internetwork dependencies, XBP versions 2.0 and 3.0 are

supported, with the following differences:

XBP version 2.0

SAP events can release Tivoli Workload Scheduler internetwork dependencies

only if the dependencies are created or checked before the SAP event is raised.

An event history is ignored, therefore, an SAP event raised before the

internetwork dependency is created, is not considered.

Note: Because an SAP event history is ignored, for each SAP event to be

checked, a placeholder SAP job is created. This is a dummy job whose

running depends on the SAP event, therefore a SAP event is considered

raised as soon as the corresponding placeholder job has completed.

XBP version 3.0 (supported by SAP NetWeaver 7.0 with SP 9, or later)

Only the SAP events stored in the SAP event history table are considered by

Tivoli Workload Scheduler to check for internetwork dependencies resolution.

As a prerequisite, the SAP administrator must create the appropriate event

history profiles and criteria on the target SAP system.

To avoid performance reduction, run reorganization tasks against the SAP event

history.

Note: Some SAP systems providing XBP version 3.0 still return XBP version as

2.0. To check if your SAP system provides XBP 3.0, invoke the

transaction SE37 and search for the function module

BAPI_XBP_BTC_EVTHISTORY_GET. If your system contains the module, set


|

|

|

|||

|

||

|

|

||

|||||||

|||

||

|||||

||||

|||||

||

||||

the xbpversion option to 3. In this way, r3batch will ignore the XBP

value returned by the SAP system. For details about the xbpversion

option, refer to Table 33 on page 106.

To define an SAP event as an internetwork dependency, use the following

parameters:

Table 43. Parameters to define an SAP internetwork dependency


GUI

support

-evtid

sap_event_name

The name of the SAP event, up to 32 characters. If the

name contains blanks, enclose it between single quotes.


U

-evtpar

sap_event_parm

The SAP event parameter, up to 64 characters. If the

parameter contains blanks, enclose it between single

quotes. This parameter is optional.

U

-commit Defines that the SAP event is committed immediately

after the internetwork dependency has been resolved. If

you do not specify -commit, the event must be committed

by running the r3batch task PI. The default is that

-commit is not specified. For details about the PI task,

refer to “Committing SAP events by an external task” on

page 187.

In addition to this parameter, you can set as default that

the system commits internetwork dependencies

immediately by specifying commit_dependency=on in the

options file. For details about the commit_dependency

option, see Table 33 on page 106.

Note: With XBP version 2.0, defining two internetwork

dependencies on the same SAP event might lead to an

error, if -commit is specified. For example, suppose you

define an internetwork dependency for the SAP event

SAPEVT, with or without setting -commit. After this

definition, the SAP event SAPEVT is raised. Then you

define a second internetwork dependency based on

SAPEVT, specifying -commit. The second dependency

immediately commits the SAP event, with the

consequence that the first dependency becomes

impossible to resolve. Therefore, when the first job checks

for the internetwork dependency, an error is issued.

U

The following example shows how to define an internetwork dependency based on

the SAP event named SAP_TEST with the parameter 12345678. After its processing,

the event is not immediately committed.

-evtid SAP_TEST -evtpar 12345678

The resulting internetwork dependency looks like the following, where SAPWS is the

name of the Extended Agent CPU that connects to the SAP background processing

system where the event runs:

follows SAPWS::"-evtid SAP_TEST -evtpar 12345678"

The following example shows how to define an internetwork dependency based on

the SAP event named SAP_TEST, without parameter. As soon as the internetwork

dependency is resolved, the event is committed.



|||

||

||

||||

|||||

|

|||||

|

||||||||

|||||

||||||||||||

|

|

|||

|

|||

|

|||

-evtid SAP_TEST -commit

The resulting internetwork dependency looks like the following, where SAPWS is the

name of the Extended Agent CPU that connects to the SAP background processing

system where the event runs:

follows SAPWS::"-evtid SAP_TEST -evtpar 12345678"

Table 44 shows the correspondence between the definition and possible resolution

of an internetwork dependency that depends on an SAP event, with or without

parameters assigned. In this table, SAP_TEST is used as the event name and

12345678 or ABCDEFG as the event parameter.

Table 44. Internetwork dependency definition and possible resolution


internetwork dependency

specified

SAP event raised

in SAP system

SAP event

parameter

Tivoli Workload

Scheduler

internetwork

dependency

resolved

-evtid SAP_TEST none none No

-evtid SAP_TEST END_OF_JOB none No

-evtid SAP_TEST SAP_TEST none Yes

-evtid SAP_TEST SAP_TEST 12345678 Yes

-evtid SAP_TEST -evtpar

12345678

SAP_TEST none No


12345678

SAP_TEST 12345678 Yes


12345678

SAP_TEST ABCDEFG No

Committing SAP events by an external task

SAP events defined as Tivoli Workload Scheduler internetwork dependencies, by

default are not automatically committed after their processing. You can modify this

default by specifying the -commit parameter. Otherwise, if you leave the default,

you must commit the processed event by the external task Put Information (PI).

The PI task commits all the processed events that meet the given criteria. For this

reason, it is recommended that you run this task at the end of the working day. By

doing so, internetwork dependencies that are already resolved are not reset and the

objects depending on them are not blocked until they are resolved again.

From a command line, enter the following command:

Command syntax

�� -r3batch -t PI -c cpu_name -- ″ -t CE -evtid sap_event_name �

� -evtpar

sap_event_parm ″ ��

Where:

-t PI

The identifier of the task to be performed, in this case PI (Put Information).



Chapter 22. Defining internetwork dependencies and event rules based on SAP R/3 events 187

|

|||

|

||||

||

|||||||

|||||

||||

||||

||||

||||

|||||

|||||

|||||

|

|

||||

||||

|

|

||||||||||||||||||

|||||||||||||||||

||

|||

-c cpu_name

The CPU name of the SAP background processing system where the event is

run. This parameter is required.

-t CE

The identifier of the task to be performed, in this case CE (Commit Event). This

parameter is required.

-evtid sap_event_name

The name of the SAP R/3 event running on the background processing system.

If the name contains blanks, enclose it between single quotes. This parameter is

required.

-evtpar sap_event_parm

The parameter of the SAP event running on the background processing system.

If the parameter contains blanks, enclose it between single quotes. This

parameter is optional. If you do not specify it, all the SAP events with the

name you specified, with or without a parameter, are committed on the target

system.

The following is an example of how to commit the SAP event named SAP_TEST,

with parameter 1234567, running on the background processing system named

tivoli10:

r3batch -t PI -c tivoli10 -- " -t CE -evtid SAP_TEST -evtpar 1234567"

Defining internetwork dependencies based on SAP events with the Job

Scheduling Console

To define an SAP event as an internetwork dependency with the Job Scheduling

Console, perform the following steps:

1. Run a list of job streams and double-click the job stream you want to manage.

The Job Stream Editor panel opens.

2. In the Actions list, select Add Dependency on Internetwork. The Internetwork

Dependency panel opens.

3. In the Network Agent field, enter the CPU name of the SAP background

processing system where the event runs.

4. In the Dependency field, enter the parameters to define the internetwork

dependency. For a description of the parameters allowed, refer to Table 43 on

page 186.

5. Click OK to save and close the panel, and return to the Job Stream Editor. You

have created the dependency.

6. To link the dependency to the job you want, in the Actions list select Add Link.

There is no visible result when you click Add Link. You must click the

dependency icon you want to link, hold down the mouse button and drag the

link to the job icon.

7. Save the Job Stream Editor panel.



|||

|||

||||

||||||

|||

|

||

|

||

||

||

||

|||

||

||||

|

|

Defining event rules based on SAP events

A scheduling event rule defines a set of actions to run when specific event

conditions occur. The definition of an event rule correlates events and triggers

actions.

An event rule is identified by a rule name and by a set of attributes that specify if

the rule is active, the time frame of its validity, and other information required to

decide when actions are triggered. It includes information related to the specific

events (eventCondition) that the rule must detect and the specific actions it is to

trigger upon their detection or timeout (ruleAction). Complex rules might include

multiple events and multiple actions.

If you are using XBP 3.0, only the SAP events that are stored in the event history

table are considered by Tivoli Workload Scheduler.

To define event rules, you can use either of the following:

The composer command line

You edit the rules with an XML editor of your choice. For details about how to

use the composer to define event rules, see the IBM Tivoli Workload Scheduler:

Reference Guide.

The Tivoli Dynamic Workload Console


The SAP event is identified by the following information:

Event name

The name of the SAP event. Wildcards are not allowed.

If you are using the Tivoli Dynamic Workload Console and you want to specify

an event name that contains the special character asterisk (*), percentage (%), or

question mark (?), use the backslash (\) immediately before the special

character. For example, if the name of the SAP event is SAP*NAME, specify it

as SAP\*NAME.

Event parameter

The parameter associated with the SAP event, if any. Wildcards are not

allowed.

If you are using the Tivoli Dynamic Workload Console and you want to specify

a parameter that contains the special character asterisk (*), percentage (%), or

question mark (?), use the backslash (\) immediately before the special

character. For example, if the parameter of the SAP event is SAP?PARM, specify

it as SAP\?PARM.

Extended agent workstation

The name of the extended agent workstation responsible for the event

monitoring.

Notes:

1. If you specify a pattern with the wildcard asterisk (*), all the extended

agents whose name matches the pattern will monitor the specified event.

2. As a best practice, define that an event belonging to an SAP system is

monitored by one extended agent workstation only. If the same SAP event

is monitored by more than one extended agent, you might either be notified



||

|||

||||||

||

|

||||

||

|

||

|||||

|||

|||||

|||

|

||

|||

multiple times for the same event occurrence or the first extended agent

that notifies the event occurrence makes that event unavailable to the other

extended agents.

3. If you modify the extended agent configuration in the r3batch option files,

to make the changes effective you must stop and restart the agent.

Prerequisite to defining event rules based on SAP

To be able to define event rules based on one or more SAP events, stop the Tivoli

Workload Scheduler WebSphere Application Server and copy the following file

(located on the system where you installed Tivoli Workload Scheduler for

Applications 8.4):

twshome/methods/SAPPlugin/SapMonitorPlugIn.jar

to the following directory of the master domain manager and of its backup nodes:

twshome/eventPlugIn

For the changes to take effect, stop and restart the Tivoli Workload Scheduler

WebSphere Application Server. If the master domain manager is connected to the

Tivoli Dynamic Workload Console, stop and restart also the Tivoli Dynamic

Workload Console Application Server.

Monitoring SAP events

Whenever you define an event rule based on an SAP event in your Tivoli

Workload Scheduler plan, that event is monitored by Tivoli Workload Scheduler.

Monitoring SAP events is allowed only if you use XPB version 3.0, or later.

Tivoli Workload Scheduler monitors two types of SAP event:

Events defined by the SAP system

The events that are triggered automatically by system changes, for example

when a new operation mode is activated. This type of event cannot be modified

by the user.

Events defined by the user

The events that are triggered by ABAP or external processes, for example when

a process triggers an SAP event to signal that external data has arrived and

must be read by the SAP system. For details about how to trigger events by

external processes, refer to “Raising an SAP event” on page 145.

If you modify the r3batch option files, to make the changes effective you must

stop and restart the extended agent monitoring processes with the following

command. For UNIX only, this command must be entered by the owner of the

Tivoli Workload Scheduler installation:

Command syntax

�� r3evman start

stop ��

Where:

start | stop The action to perform:

start Starts monitoring SAP events.

stop Stops monitoring SAP events.



|||

||

|

||||

|

|

|

1111

|

|||

|

||||

|||||

||||

|

||||||||||||||||

|

|

||

||

||

SAP events matching criteria

The SAP events specified in the event rule are matched with the events raised in

the SAP system, according to the following criteria. Depending on the parameters

you set:

The SAP event name and parameter are specified in the event rule

To match, the SAP event name and parameter must be the same as the event ID

and event parameter raised in the SAP system. Also, the event state must be N

(New). SAP events with a different parameter or without any parameter are

ignored.

The information collected about the matching SAP event is sent by the r3evmon

process to Tivoli Workload Scheduler. If the notification is successfully sent, the

event is committed on the SAP system and its state changed to C (Confirmed).

For example, you define an event rule in your Tivoli Workload Scheduler plan

based on the following SAP event:

SAP event name SAP_TEST

SAP event parameter ABCDEF

Extended agent workstation GENIUS

According to these settings, a file named GENIUS_r3evmon.cfg is created on

GENIUS. It contains the following !R3EVENT keyword:

!R3EVENT 0008SAP_TEST0006ABCDEF

Monitoring of the SAP_TEST event with parameter ABCDEF is automatically

started. Suppose that the following SAP events were raised on the SAP system:

Table 45. History table of the SAP events raised

EVENT

GUID

EVENT

ID

EVENT

PARM

EVENT

SERVER

EVENT

TIMESTAMP

EVENT

STATE

PROCESS

STATE

COUNT

OF

JOBS

1234 SAP_TEST ABC123 ... 20070925 13:00 C OK 1

2345 SAP_TEST ABCD ... 20070925 14:00 N OK 2

3456 SAP_TEST ... 20070925 15:00 N OK 3

4567 SAP_TEST ABCDEF ... 20070925 16:00 N OK 4

Only the following SAP event is notified to Tivoli Workload Scheduler:

Table 46. SAP event matching with the event rule defined

EVENT

GUID

EVENT

ID

EVENT

PARM

EVENT

SERVER

EVENT

TIMESTAMP

EVENT

STATE

PROCESS

STATE

COUNT

OF

JOBS


If the notification is successfully sent, the event is committed on the SAP

system and its state changed to C (Confirmed).

Only the SAP event name is specified in the event rule

To match, the SAP event name must be the same as the ID of the events raised

in the SAP system whose state is N (New). The parameters of the SAP events,

whether specified or not, are not taken into account.

The information collected about all the matching SAP events is sent by the

r3evmon process to Tivoli Workload Scheduler. Each event successfully notified

is committed on the SAP system and its status changed to C (Confirmed).



||||

|||||

|||

||

||

||

||

||

|

||

||

||||||||||||||

|||

||||||||

||||||||

||||||||

||||||||||

||

||||||||||||||

|||

|||||||||||

||||

|||

For example, you define an event rule in your Tivoli Workload Scheduler plan

based on the following SAP event:

SAP event name SAP_TEST

Extended agent workstation GENIUS

According to these settings, a file named GENIUS_r3evmon.cfg is created on

GENIUS. It contains the following !R3EVENT keyword:

!R3EVENT 0008SAP_TEST

Monitoring of the SAP_TEST event is automatically started. Suppose that the

following SAP events were raised on the SAP system:

Table 47. History table of the SAP events raised

EVENT

GUID

EVENT

ID

EVENT

PARM

EVENT

SERVER

EVENT

TIMESTAMP

EVENT

STATE

PROCESS

STATE

COUNT

OF

JOBS

1234 SAP_TEST ABC123 ... 20070925 13:00 C OK 1

2345 SAP_TEST ABCD ... 20070925 14:00 N OK 2

3456 SAP_TEST ... 20070925 15:00 N OK 3


Only the following SAP events are notified to Tivoli Workload Scheduler:

Table 48. SAP events matching with the event rule defined

EVENT

GUID

EVENT

ID

EVENT

PARM

EVENT

SERVER

EVENT

TIMESTAMP

EVENT

STATE

PROCESS

STATE

COUNT

OF

JOBS

2345 SAP_TEST ABCD ... 20070925 14:00 N OK 2

3456 SAP_TEST ... 20070925 15:00 N OK 3


Each event whose notification is successfully sent is committed on the SAP

system and its state changed to C (Confirmed).

Setting a filter for SAP events in the security file

In the security file, you can filter the SAP events that can be used to define event

rules. By doing so, you restrict the use of certain SAP events to specific users. For

example, assume that you want your USA department to manage only the SAP

events whose ID begins with SAP_USA, and your Italy department to manage all

events except those beginning with SAP_USA. In the security file that defines the

user access for the USA department, define the CUSTOM keyword for the EVENT

object as follows:

EVENT PROVIDER=@ +CUSTOM=SAP_USA@ ACCESS=USE

where:

PROVIDER=@ Specifies that the user can use the events coming from any

provider.

+CUSTOM=SAP_USA@

Specifies that the user can use only the SAP events whose ID

begins with SAP_USA.

This keyword applies only to the SAP provider (SapMonitor).



||

||

||

||

|

||

||

||||||||||||||

|||

||||||||

||||||||

||||||||

||||||||||

||

||||||||||||||

|||

||||||||

||||||||

|||||||||||

||

|||||||

|

|

|||

|||

|

ACCESS=USE Sets the user access to the object to USE.

In the security file that defines the user access for the Italy department, define the

CUSTOM keyword for the EVENT object as follows:

EVENT PROVIDER=@ ~CUSTOM=SAP_USA@ ACCESS=USE

where:

PROVIDER=@ Specifies that the user can use the events coming from any

provider.

~CUSTOM=SAP_USA@

Specifies that the user can use all SAP events, except those whose

ID begins with SAP_USA.

This keyword applies only to the SAP provider (SapMonitor).

ACCESS=USE Sets the user access to the object to USE.

For more details about the security file and how to set up user authorizations, see

the IBM Tivoli Workload Scheduler: Reference Guide.



||

||

|

|

|||

|||

|

||

||


Chapter 23. Defining event rules based on IDoc records

With Tivoli Workload Scheduler for Applications, you can monitor Intermediate

Document (IDoc) records in SAP systems and forward events to the Tivoli

Workload Scheduler’s event integration framework. You define an event condition

that contains the criteria that the IDocs must match to be forwarded to Tivoli

Workload Scheduler. When the event condition occurs, the action you associated

with it (for example, running a job) is performed.

In this chapter:

v “Business scenario” provides a real-life example of how you can use event rules

based on IDocs in your business environment.

v “Creating event rules based on IDocs” on page 196 describes the fields you can

specify as matching criteria for the IDoc monitoring process.

v “Examples of event rules based on IDocs” on page 201 shows some examples.

Business scenario

You connected your Internet sales application to your SAP Customer Relationship

Management (CRM) system, which receives the orders as incoming IDocs. The

orders are classified as emergency and ordinary, therefore have different IDoc

message types. You want the emergency orders to be imported into the CRM

system directly, and the ordinary orders to be processed in batch mode. To do this,

in Tivoli Workload Scheduler for Applications, you define an event rule that

monitors the IDoc message types corresponding to emergency orders and sends an

event to Tivoli Workload Scheduler. In Tivoli Workload Scheduler, you define a job

to be released when this type of event is received and is linked to an SAP job that

runs an import ABAP report for these specific types of IDocs.

InternetOrderSystem

SAPMonitors IDocs

TivoliWorkloadScheduler

orderIDocs

Triggers immediate import

for high priority orders

CRM

DI octables

Figure 25. Managing high priority IDocs overview


1

1111

1

1

111111

111111

11

11111111111

Creating event rules based on IDocs

To define event rules based on IDocs, specify the fields to be used as matching

criteria during IDoc monitoring. For details about these fields, refer to “Events

matching criteria.” To create the event rules, you can use either of the following:

The composer command line

You edit the rules with an XML editor of your choice. For a general explanation

about how to use the composer to define event rules, see the IBM Tivoli

Workload Scheduler: Reference Guide. The event condition requires:

v SAPMonitor as event monitor provider.

v IDOCEventGenerated as event type.

For a list of the values you can specify in the attributeFilter name when

defining the event condition, refer to Table 51 on page 198.

The Tivoli Dynamic Workload Console


Events matching criteria

Table 49 lists the Tivoli Workload Scheduler fields corresponding to the fields in

the IDoc record that you want to search. During monitoring, each IDoc matching

the search criteria generates an event that is sent to Tivoli Workload Scheduler.

Table 49. Tivoli Workload Scheduler fields used to define event rules

Composer property Console property IDoc field

SAPClient SAP client MANDT

SAPIDocStatus Status STATUS

SAPDirectionIDocTransmission Direction DIRECT

SAPReceiverPort Receiver port RCVPOR

SAPReceiverPartnerFunction Receiver partner function RCVPFC

SAPReceiverPartnerType Receiver partner type RCVPRT

SAPReceiverPartnerNumber Receiver partner number RCVPRN

SAPSenderPort Sender port SNDPOR

SAPSenderPartnerType Sender partner type SNDPRT

SAPSenderPartnerFunction Sender partner function SNDPFC

SAPSenderPartnerNumber Sender partner number SNDPRN

SAPLogicalMessageType Logical message type MESTYP

SAPNameOfBasicType Name of basic type IDOCTP

SAPLogicalMessageCode Logical message code MESCOD

SAPLogicalMessageFunction Logical message function MESFCT

SAPTestFlag Test flag TEST

SAPOutputMode Output mode OUTMOD

Optionally, you can define also correlation rules by using the fields listed in

Table 50 on page 197:



11

111

1111

1

1

11

11

1

111

11

111

111

111

111

111

111

111

111

111

111

111

111

111

111

111

111

111

1111

11

Table 50. Tivoli Workload Scheduler fields used to define correlation rules

Composer property Console property IDoc field

SAPIDocNumber IDoc number DOCNUM

SAPReleaseForIDoc IDoc SAP release DOCREL

SAPIDocType IDoc type DOCTYP

SAPReceiverAddress Receiver SADR address RCVSAD

SAPReceiverSADRClient Receiver SADR client RCVSMN

SAPFlagForInternationalReceiverAddress Receiver SADR flag RCVSNA

SAPReceiverCommunicationType Receiver SADR

communication type

RCVSCA

SAPDefaultFlagForReceiverAddress Receiver SADR default flag RCVSDF

SAPReceiverAddressSequentialNumber Receiver SADR sequential

number

RCVSLF

SAPReceiverLogicalAddress Receiver logical address RCVLAD

SAPEDIStandard EDI Standard STD

SAPEDIStandardVersion EDI standard version STDVRS

SAPEDIMessageType EDI message type STDMES

SAPSenderAddress Sender SADR address SNDSAD

SAPSenderSADRClient Sender SADR client SNDSMN

SAPFlagForInternationalSenderAddress Sender SADR flag SNDSNA

SAPSenderCommunicationType Sender SADR

communication type

SNDSCA

SAPDefaultFlagForSenderAddress Sender SADR default flag SNDSDF

SAPSenderAddressSequentialNumber Sender SADR sequential

number

SNDSLF

SAPSenderLogicalAddress Sender logical address SNDLAD

SAPReferenceToInterchangeFile Interchange file reference REFINT

SAPReferenceToMessageGroup Message group reference REFGRP

SAPReferenceToMessage Message reference REFMES

SAPEDIArchiveKey EDI archive key ARCKEY

SAPIDocCreationDate IDoc creation date CREDAT

SAPIDocCreationTime IDoc creation time CRETIM

SAPExtension Extension CIMTYP

SAPEDIALESerializationField EDI/ALE Serialization field SERIAL

SAPOverridingInInboundProcessing Overriding in inbound

processing

EXPRSS

SAPIDocChangeDate IDoc last update date UPDDAT

SAPIDocChangeTime IDoc last update time UPDTIM

Based on the defined rule, the r3evmon process of Tivoli Workload Scheduler for

Applications monitors the events related to IDoc records according to a polling

rate. To customize this polling rate, use the evmon_interval option; for details, see

“Defining the common options” on page 106.


Chapter 23. Defining event rules based on IDoc records 197

11

111

111

111

111

111

111

111

1111

111

1111

111

111

111

111

111

111

111

1111

111

1111

111

111

111

111

111

111

111

111

111

1111

111

1111

1111

Table 51 lists the values you can specify as attribute filter name when defining the

event condition.

Table 51. Parameters of IDOCEventGenerated event type

Property name Description Type

Filtering

allowed

Required

Multiple

values

allowed

Wildcard

allowed

Length

(min-max)

SAPClient SAP client number numeric (0-9) U U U 1 3

SAPIDocStatus

IDoc status

information

For a list of allowed

values, refer to

Table 52 on page 199

and Table 53 on

page 200.

numeric U U U 1 2

SAPDirectionIDocTransmission IDoc direction

numeric

Value can be:

1 outbound

2 inbound

U U 1 1

SAPReceiverPort

Receiver port. SAP

system, EDI

subsystem

string U 1 10

SAPReceiverPartnerFunction

Partner function of

receiver

string U 1 2

SAPReceiverPartnerType

Partner type of

receiver

string U 1 2

SAPReceiverPartnerNumber

Partner number of

receiver

string U 1 10

SAPSenderPort

Sender port. SAP

system, EDI

subsystem

string U 1 10

SAPSenderPartnerType

Partner type of

sender

string U 1 2

SAPSenderPartnerFunction

Partner function of

sender

string U 1 2

SAPSenderPartnerNumber

Partner number of

sender

string U 1 10

SAPLogicalMessageType

Logical message

type

string U U 1 30

SAPNameOfBasicType Name of basic type string U U 1 30

SAPLogicalMessageCode

Logical message

code

string U 1 3

SAPLogicalMessageFunction

Logical message

function

string U 1 3

SAPTestFlag Test flag string U 1 1

SAPOutputMode Output Mode

string

Value can be:

2 immediate

sending

4 collected

sending

U 1 1

Table 52 on page 199 lists the standard outbound IDoc statuses and Table 53 on

page 200 lists the standard inbound IDoc statuses. Optionally, you can activate a

check to prevent event rule definitions with inconsistent IDoc status list and

direction. If you activate the check and specify inconsistent values when defining a

rule (for example, 02 as status and 2 as direction), you receive an error message

and you cannot save the rule definition. To activate the check, perform the

following steps:



11

11

1111111111111

111111111

1

11

11111

1111111

11

1

11111

111111

11111111111

1111111111

1111111111

1111111111

11111111111

1111111111

1111111111

1111111111

1111111111

111111111

1111111111

1111111111

111111111

11

1

1111111

111111

1

1111111

1. In the twshome/eventPlugIn directory, create the SapMonitorPlugIn.properties

file.

2. Edit SapMonitorPlugIn.properties to set the following configuration property:

TWSPlugIn.event.idoc.consistency.check = true

3. From conman, stop and restart the event processing server by using,

respectively, the stopeventprocessor and starteventprocessor commands.

The default value is false.

To have predictable event action results, when defining event rules consider using

only non-transitory statuses that allow user checks.

Table 52. Standard outbound IDoc statuses

Status Description

01 IDoc generated

02 Error passing data to port

03 Data passed to port

04 Error within control information of EDI subsystem

05 Error during translation

06 Translation

07 Error during syntax check

08 Syntax check

09 Error during interchange

10 Interchange handling

11 Error during dispatch

12 Dispatch OK

13 Retransmission OK

14 Interchange acknowledgement positive

15 Interchange acknowledgement negative

16 Functional acknowledgement positive

17 Functional acknowledgement negative

18 Triggering EDI subsystem OK

19 Data transfer for test OK

20 Error triggering EDI subsystem

22 Dispatch OK, acknowledgement still due

23 Error during retransmission

24 Control information of EDI subsystem OK

25 Processing despite syntax error

26 Error during syntax check of IDoc

27 Error in dispatch level (ALE service)

29 Error in ALE service

30 IDoc ready for dispatch (ALE service)

31 Error no further processing

32 IDoc was edited

33 Original of an IDoc which was edited



11

1

1

11

1

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

Table 52. Standard outbound IDoc statuses (continued)

Status Description

34 Error in control record of IDoc

36 Electronic signature not performed (timeout)

37 IDoc added incorrectly

38 IDoc archived

39 IDoc is in the target system (ALE service)

40 Application document not created in target system

41 Application document created in target system

42 IDoc was created by test transaction

Table 53. Standard inbound IDoc statuses

Status Description

50 IDoc added

51 Application document not posted

52 Application document not fully posted

53 Application document posted

54 Error during formal application check

55 Formal application check OK

56 IDoc with errors added

57 Error during application check

58 IDoc copy from R/2 connection

60 Error during syntax check of IDoc

61 Processing despite syntax error

62 IDoc passed to application

63 Error passing IDoc to application

64 IDoc ready to be transferred to application

65 Error in ALE service

66 IDoc is waiting for predecessor IDoc (serialization)

68 Error - no further processing

69 IDoc was edited

70 Original of an IDoc which was edited

71 IDoc reloaded from archive

73 IDoc archived

74 IDoc was created by test transaction

For example, you define a rule with the following attributes:

Extended agent workstation SAPCPU

SAP client number 001

IDoc status list 56,60

IDoc direction 2 (inbound)



1

11

11

11

11

11

11

11

11

111

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

11

111

1

11

11

11

11

After saving the rule according to these settings, when the rule becomes active a

file named SAPCPU_r3evmon.cfg is created on SAPCPU. It contains the following

!IDOC keyword:

!IDOC 0003001000556,600001200000000000000000000000000000000000000000000000000000000

IDoc monitoring is automatically started. When the event condition is verified, the

action defined in the rule is triggered

For an explanation of the !IDOC keyword format, refer to Table 69 on page 257.

Examples of event rules based on IDocs

The following example applies to the scenario described in “Business scenario” on

page 195. It shows an event rule that triggers an import ABAP report when an

IDoc is added with a message type corresponding to emergency orders.

<?xml version="1.0" encoding="UTF-8"?>

<eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules"

xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/

event-management/rules EventRules.xsd">

<eventRule name="scenario1_IDoc" ruleType="filter" isDraft="no">

<eventCondition name="IDocEventRaised1" eventProvider="SapMonitor"

eventType="IDocEventGenerated">

<scope>

001 ON SAPCU WITH 2

<scope>

<filteringPredicate> <attributeFilter name="Workstation" operator="eq">

<value>SAPCPU</value>

</attributeFilter>

<attributeFilter name="SAPClient" operator="eq">

<value>001</value>

</attributeFilter>

<attributeFilter name="SAPIDocStatus" operator="eq">

<value>50</value>

</attributeFilter>

<attributeFilter name="SAPDirectionIDocTransmission" operator="eq">

<value>2</value>

</attributeFilter>

<attributeFilter name="SAPLogicalMessageType" operator="eq">

value>EORD1</value>

</attributeFilter>

</filteringPredicate>

</eventCondition>

<action actionProvider="TWSaction" actionType="sbj"

responseType="onDetection">

<description>Trigger immediate report for high priority orders

</description>

<parameter name="JobDefinitionWorkstationName">

<value>MASTER84</value>

</parameter>

<parameter name="JobDefinitionName">

<value>triggerimport</value>

</parameter>

</action>

</eventRule>

</eventRuleSet>

The following example shows an event rule defined to create a ticket for failing

IDocs in the SAP Solution Manager or any other problem management system:

when an IDoc with a syntax error is detected, the engine submits a job to create a

ticket for the failing IDoc.



111

1

11

1

11

111

111111111111111111111111111111111111111111

1111

<?xml version="1.0" encoding="UTF-8"?>

<eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules"

xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/

event-management/rules EventRules.xsd">

<eventRule name="scenario1_IDoc" ruleType="filter" isDraft="no">

<eventCondition name="IDocEventRaised1" eventProvider="SapMonitor"

eventType="IDocEventGenerated">

<filteringPredicate> <attributeFilter name="Workstation" operator="eq">

<value>SAPCPU</value>

</attributeFilter>

<attributeFilter name="SAPClient" operator="eq">

<value>001</value>

</attributeFilter>

<attributeFilter name="SAPIDocStatus" operator="eq">

<value>60</value>

<attributeFilter name="SAPDirectionIDocTransmission" operator="eq">

<value>2</value>

</attributeFilter>

</attributeFilter>

<attributeFilter name="SAPLogicalMessageType" operator="eq">

value>MYORD1</value>

</attributeFilter>

</filteringPredicate>

</eventCondition>

<action actionProvider="TWSaction" actionType="sbj"

responseType="onDetection">

<description>Create a ticket for failing IDocs

</description>

<parameter name="JobDefinitionWorkstationName">

<value>MASTER84</value>

</parameter>

<parameter name="JobDefinitionName">

<value>createticket</value>

</parameter>

</action>

</eventRule>

</eventRuleSet>

Examples of event rules based on IDocs


111111111111111111111111111111111111111

Chapter 24. National Language support

Using the local and global configuration files, you can set up r3batch to use

different code pages and languages for both its output and the connection with a

remote R/3 system.

The National Language support feature allows you to install r3batch on a localized

Tivoli Workload Scheduler workstation and use localized characters for Tivoli

Workload Scheduler job names, job streams, and R/3 variants.

As explained in “Unicode support” on page 93, this version of Tivoli Workload

Scheduler for Applications for SAP features Unicode, which is widely supported

by R/3 systems since version 4.7. However, if either the workstation running

r3batch or the target R/3 systems do not support Unicode, this chapter describes

how you configure code pages and national languages for r3batch.

Setting National Language support options

The following options control the code page and national language used by Tivoli

Workload Scheduler for Applications for SAP version 8.2.1, when Unicode support

is not used:

TWSXA_CP

The code page used to establish the connection between r3batch and the target

SAP R/3 system.

If you are running a non-Unicode version of r3batch, set this option to the code

page installed on the SAP R/3 system (for a list of the valid code pages, refer

to “SAP R/3 supported code pages” on page 204). The default value is the SAP

R/3 code page 1100, similar to the standard ISO8859-1. In all other cases, this

option is ignored.

TWSXA_LANG

The language that r3batch uses to log in. It can be one of the following:

v Brazilian Portuguese (pt_BR)

v English (EN, the default value)

v French (FR)

v German (DE)

v Italian (IT)

v Japanese (JA)

v Korean (KO)

v Simplified Chinese (zh_CN)

v Spanish (ES)

v Traditional Chinese (zh_TW)

DE, EN, and JA can be set from the Option Editor. The other languages can be

set using any text editor.


1

|||

|||||

TWSMETH_CP

The code page that r3batch uses for its output. The default is the code page

used by the Tivoli Workload Scheduler workstation that hosts r3batch.

Ensure that the TWSMETH_CP and TWSMETH_LANG options are consistent.

TWSMETH_LANG

The catalog language used by r3batch. The default is the language used by the

Tivoli Workload Scheduler workstation that hosts r3batch.

Ensure that the TWSMETH_CP and TWSMETH_LANG options are consistent.

SAP R/3 supported code pages

To communicate with SAP R/3 systems, Tivoli Workload Scheduler for

Applications for SAP uses the following code pages. Use these values to set option

TWSXA_CP, only when r3batch does not support Unicode.

Table 54. SAP R/3 supported code pages

SAP R/3 code pages Description

1100 8859-1, this is the default value

1103 MS 850

8000 SJIS: Shift JIS

8300 BIG5: Traditional Chinese

8400 GBK: Simplified Chinese

Supported configurations and limitations

The following is a limitation of the Job Scheduling Console version 1.2.

Even if both the r3batch and the target R/3 system are Unicode-supporting

versions, to retrieve the r3batch output, you must run the Job Scheduling Console

on a system that uses the same code page as the Tivoli Workload Scheduler

workstation where r3batch is installed. If the hosting agent uses MS932, run the

Job Scheduling Console on a Japanese system with that code page.

Job Scheduling Console version 1.3, and later, interact with r3batch via UTF-8,

therefore this limitation no longer exists.

Setting National Language support options






Applications for z/OS

Using Tivoli Workload Scheduler for Applications for z/OS you can schedule and

control z/OS jobs using the job scheduling features of Tivoli Workload Scheduler.

Note: Throughout this publication, the term z/OS is used to refer also to

supported versions of OS/390. For detailed information, see “Software

requirements.”

This chapter contains the following sections:

v “Software requirements”

v “Features”

v “Installing, configuring, and uninstalling the z/OS gateway” on page 208

v “Additional information” on page 212

v “Downloading z/OS gateway fixes from FTP” on page 218





Table 55. Additional z/OS software requirements

Software Requirement Version

TCP/IP One of the following:

v IBM 3.1, or later

v Interlink 3.1, or later

v Open Connect 2.3, or later

Job Scheduling Interface v JES2 or JES3.

Note: In a z/OS Parallel Sysplex® environment, a JES

job must be run on the LPAR where it is submitted.

v OPC interface: IBM Tivoli Workload Scheduler for

z/OS.

v CA-7 interface: any currently supported version.

Note: Support to IPv6 is provided only with Tivoli Workload Scheduler, version 8.4 or

later, for TCP/IP on IBM 3.1, or later.

Features

Using Tivoli Workload Scheduler for Applications for z/OS you can:

v Use Tivoli Workload Scheduler to schedule z/OS jobs to run at specific times

and in a prescribed order.

v Define dependencies between Tivoli Workload Scheduler jobs running on

different systems and operating systems.

v Define dependencies for Tivoli Workload Scheduler jobs based on the

completion of z/OS jobs that were not launched by Tivoli Workload Scheduler.


v Define dependencies for Tivoli Workload Scheduler jobs based on the existence

of files on a z/OS system.



operation of the product. Table 56 describes the roles and responsibilities of all the

users in the process model, showing the tasks they perform.

Table 56. Roles and responsibilities in Tivoli Workload Scheduler for Applications for z/OS

User role User task

z/OS administrator v “Installing, configuring, and uninstalling the z/OS

gateway”

v “Downloading z/OS gateway fixes from FTP” on

page 218






“Defining z/OS jobs in Tivoli Workload Scheduler”

on page 223

Installing, configuring, and uninstalling the z/OS gateway

Tivoli Workload Scheduler for Applications for z/OS consists of the z/OS access

method that must reside on the Tivoli Workload Scheduler host, and of the

gateway software that resides on z/OS. To install the Tivoli Workload Scheduler

for Applications for z/OS access method and its language pack, refer to Chapter 2,

“Installing, upgrading, and uninstalling IBM Tivoli Workload Scheduler for

Applications,” on page 5.

To install, configure, and uninstall the z/OS gateway, refer to the following

sections:

v “Installing”

v “Configuring” on page 210

v “Uninstalling” on page 211

Installing

You can install the z/OS gateway module in either of these two ways:

v Unload the files from the IBM Tivoli Workload Scheduler for Applications CD.

See “Unloading the files from the CD.”

v Unload the files from a 3480 tape cartridge written in non-IDRC (uncompressed)

format. See “Unloading the files from the tape” on page 209.

Unloading the files from the CD

The z/OS gateway files are stored in the ZOS directory of the product CD and are

named:

v LOADLIB

v SAMPLES

To unload the files onto your z/OS system:

1. From your TSO session emulator, select the ISPF command shell (TSO

command) and use the File Transfer utility (Send to Host) to transfer the

Features


|

|||

||

||

|||

||

|||

|||||

|

LOADLIB library and SAMPLES member from the CD to the z/OS system,

setting the transfer for a logical record length of 80 and a fixed record format.

2. Receive the members in output data sets using the INDSN option. This unloads

12 load modules into the output library and two samples into the sample

library.

For example:

LOADLIB

1. Issue the following command:

TSO RECEIVE INDSN(’TWS4APPS.LOADLIB.L80’)

A prompt is displayed similar to the following:

INMR901I Dataset TWS84.XAGENT.V8R4M0.FIXPAC04.DRV1511.LOADLIB

from TWSUSR2 on NODENAME NMR906A

Enter restore parameters or ’DELETE’ or ’END’ +

***

2. Reply:

da(’TWS4APPS.LOADLIB’)

Where: ″da″ means ″data set″ and the MVS™ data set name in quotes is the

name you want for the output loadlib data set.

Some IEBCOPY messages are displayed as the library is uncompressed.

SAMPLIB

1. Issue the following command:

TSO RECEIVE INDSN(’TWS4APPS.SAMPLIB.L80’)


INMR901I Dataset TWS84.XAGENT.V8R4M0.FIXPAC04.DRV1511.SAMPLIB



***

2. Reply:

da(’TWS4APPS.SAMPLIB’)

Where: ″da″ means ″data set″ and the MVS data set name in quotes is the

name you want for the output samplib data set.


Unloading the files from the tape

The z/OS gateway files are supplied on a 3480 tape cartridge written in non-IDRC

(uncompressed) format.

Modify and submit the JCL below to unload the tape. Customize the job card and

modify the following parameters according to your environment standards:

v Enter an appropriate job name.

v Identify a 3480 tape device.//MVSXAUNL JOB (876903,D07),’OPCL3’,MSGLEVEL=(1,1),

// MSGCLASS=A,CLASS=A,NOTIFY=&SYSUID

//**********************************************************************

//* *

//* THIS IS THE JOB THAT UNLOADS THE TIVOLI WORKLOAD SCHEDULER FOR *

//* APPLICATIONS z/OS Access Method Version 8.4 TO CUSTOMIZE *

//* *

//**********************************************************************

Unloading the files from the CD

Chapter 25. Introducing Tivoli Workload Scheduler for Applications for z/OS 209

|||

//STEP01 EXEC PGM=IEBCOPY

//SYSPRINT DD SYSOUT=*

//INDD DD DSN=TWSX.V8R4M0.SAMPLES,

// DISP=(OLD,PASS),UNIT=600,

// VOL=SER=IBM001,

// LABEL=(1,SL)

//OUTDD DD DSN=TWSX.V8R4M0.SAMPLES,

// DISP=(NEW,CATLG),

// SPACE=(32760,(2,2,10)),

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=0),

// UNIT=3390,VOL=SER=OPC00C

//SYSUT3 DD UNIT=SYSDA,SPACE=(TRK,(20,1,10))


//SYSIN DD *

COPY OUTDD=OUTDD,INDD=((INDD,R))

//STEP02 EXEC PGM=IEBCOPY

//SYSPRINT DD SYSOUT=*

//INDD DD DSN=TWSX.V8R4M0.SERVICE.APFLIB1,

// DISP=(OLD,PASS),UNIT=600,

// VOL=SER=IBM001,

// LABEL=(2,SL)

//OUTDD DD DSN=TWSX.V8R4M0.SERVICE.APFLIB1,

// DISP=(NEW,CATLG),

// SPACE=(32760,(50,50,50)),

// DCB=(RECFM=U,BLKSIZE=32760),

// UNIT=3390,VOL=SER=OPC00C



//SYSIN DD *

COPY OUTDD=OUTDD,INDD=((INDD,R))

//*

Configuring

To configure the z/OS gateway:

1. Authorize the TWS4APPS.LOADLIB in APF, or copy its contents into another

authorized load library. See “Setting APF authorizations on z/OS” on page

211 for details.

2. Add EEWTCP00 to the AUTHCMD list in IKJTSO00 (SYS1.PARMLIB)

3. Set the RACF permissions so that the user who will use the gateway can issue

the PARMLIB command. See “Setting RACF authorizations on z/OS” on page

211 for details.

4. Make the IKJTSO00 change effective by performing an IPL, or by issuing the

following command:

PARMLIB UPDATE(00)

5. Create a PARMLIB member with the appropriate startup parameters for

EEWSPACE and EEWSERVE.

Note: This member must have the PACK OFF option set in its profile. If PACK

ON is set, the started task will end with RC=04.

6. Copy EEWSPACE and EEWSERVE to the PROCLIB ( from SAMPLIB) and edit it (for

example, include STEPLIB, and specify the appropriate PARMLIB member

name).

7. Verify that the TCP/IP port specified in the PARMLIB member is not in use. To

do this, issue the following command and review the output:

TSO NETSTAT PORTLIST

If the port is in use, choose another that is not in use and modify the PARMLIB

member.

Unloading the files from the tape


8. Ensure that the IEFU84 exit is enabled by checking the SYS1.PARMLIB member

SMFPRMxx, or by issuing the following console command:

D SMF,O

If the SMFPRMxx member must be changed, to make the changes effective issue

the command:

SET SMF=xx

9. Set the RACF permissions for the started tasks EEWSPACE and EEWSERVE.

For details, see “Setting RACF authorizations on z/OS.”

10. Start EEWSPACE.

11. When EEWSPACE is up, start EEWSERVE.

Setting APF authorizations on z/OS

This section describes how to authorize the load library in APF, by following these

steps:

1. Issuing the SETPROG command from the console log. For example:

SETPROG APF,ADD,DSN=twsx.SERVICE.APFLIB1,

VOL=xxxxxx

where: xxxxxx is the volume serial number where the load library is located, or:

SETPROG APF,ADD,DSN=twsx.SERVICE.APFLIB1,VOL=SMS

which indicates a volume controlled by SMS.

2. Update the PROGxx member of SYS1.PARMLIB, or the authorization will be lost at

your next IPL.

3. Add EEWTCP00 to the AUTCHCMD NAMES section of SYS1.PARMLIB(IKJTSOxx).

Setting RACF authorizations on z/OS

This section describes how to set RACF permissions.

To set the RACF permissions to authorize the PARMLIB command to be used by the

user "ibmuser", issue the following commands:

rdefine tsoauth parmlib uacc(upd)

permit parmlib class(tsoauth) id(ibmuser) acc(upd)

setropts raclist(tsoauth) refresh

To set the RACF permissions for the started tasks EEWSPACE and EEWSERVE,

issue the following commands:

redefine started EEWSPACE.**

stdata(user(<user_ID>) group(group_name))

redefine started EEWSERVE.**

stdata(user(<user_ID>) group(group_name))

setropts raclist(started) refresh

Uninstalling

To uninstall the z/OS gateway:

1. Stop the started tasks EEWSPACE and EEWSERVE.

2. Cancel the TWS4APPS.LOADLIB library and the TWS4APPS.SAMPLES member.

3. Remove the started task entries from the RACF database by issuing the

following commands:

rdelete started EEWSPACE.**

rdelete started EEWSERVE.**

setropts raclist(started) refresh

Configuring z/OS gateway


Additional information

The following topics provide additional information for the z/OS extended agent:

v “Gateway software components”

v “IEFU84 Exit”

v “Security”

v “Console Security” on page 213

v “Startup” on page 213

v “SYSTSIN variables” on page 213

v “z/OS gateway version” on page 217

Gateway software components

The two z/OS program components of the Tivoli Workload Scheduler gateway are:

EEWTCP02

This program establishes that Tivoli Workload Scheduler is tracking on the

z/OS system. The program is started by the EEWSPACE job.

EEWTCP00

This is the “gateway” program that manages TCP/IP communications between

Tivoli Workload Scheduler and the z/OS system. It is started by the

EEWSERVE job. EEWTCP00 translates Tivoli Workload Scheduler commands to

z/OS equivalents, routes z/OS information back to Tivoli Workload Scheduler,

and performs EBCDIC-ASCII data conversions.

Both of the programs run as started tasks, with a TIME=NOLIMIT parameter.

EEWTCP02 is always started first, followed by EEWTCP00. If the programs must

be terminated for any reason, they should be stopped, not canceled, to ensure that

they shut down properly without impacting other programs that use the IEFU84

Exit.

IEFU84 Exit

The extended agent for z/OS tracks job streams using the IEFU84 exit. This exit

must be turned on in the SMF parm member in SYS1.PARMLIB. IBM distributes a

dummy IEFU84 exit with the operating system that is an IEFBR14 program. The

EEWSPACE job dynamically chains to the IEFU84 exit. If the IEFU84 exit is

currently being used, EEWSPACE will “front-end” the IEFU84 exit, obtain the

information it requires, and then branch to the existing user exit(s). When

EEWSPACE is terminated, it removes itself from the chain and restores the chain to

its original status. It is important to note that EEWSPACE has no effect on the

existing IEFU84 exit or exits, which continue to run normally.

Security

Security is enforced in several areas, usually, RACF, Top Secret, and ACF2. The

EEWSERVE job should have the ability to submit jobs that run under the user IDs

that are supplied in the JCL to be submitted. The JCL should not contain

passwords. This can be authorized using SURROGAT class resources in RACF, and

the equivalents in ACF2 and Top Secret. PROPCNTL class resources in RACF

should be used to prevent submitted jobs from running under the EEWSERVE user

ID. ACF2 and Top Secret equivalents can also be used. Resource class JESJOBS in

RACF, and ACF2 or Top Secret equivalents, can be used to control which job

names and user IDs (with or without passwords) can be submitted by EEWSERVE.

Additional information


Console Security

The EEWSERVE job completely owns the console when displaying job streams and

issuing modify commands to CA-7. It must have the authority to use an extended

console. See your security administrator to ensure that this is the case. Note that

CA-7 must be configured to allow users to issue modify commands through the

master or extended consoles. OPERCMDS should be modified to allow this

function if not already allowed. See also “SYSTSIN variables” for information

about specifying a user ID of authority.

The following example shows the CA-7 parameters needed to support the use of

the modify command from a console:

GROUP,NAME=EEW,DEVICE=CONSL,LNAME=EEW,OPEN=YES

LINE,NAME=EEW,TNAME=EEW,BUFSIZE=150,OPEN=YES

TERM,DEVICE=CONSL,NLINE=10,LINELEN=110,NAME=EEW

STATIONS,TRMID=EEW,STANIDS=(EEW)

Startup

Follow these steps:

1. Customize and start the EEWSPACE procedure (following the commented

instructions contained therein) to start the extended agent Gateway Data Space.

The job must be a started task and must not be canceled. See “SYSTSIN

variables” for a description of parameter settings. EEWSPACE creates the Data

Space and installs the IEFU84 exit. To terminate the job, use the STOP EEWSPACE

command from any z/OS console.

Notes:

a. EEWSPACE must be active before EEWSERVE is started.

b. To shut down, stop EEWSERVE before stopping EEWSPACE.2. Customize and start the EEWSERVE procedure following the commented

instructions contained therein. See “SYSTSIN variables” for a description of

parameter settings.

3. To terminate the job, use the STOP EEWSERVE command from any z/OS console.

SYSTSIN variables

Table 57 lists all the SYSTSIN variables and their description. Modify the settings

as required for your site configuration. The default values are shown in

parentheses.

Table 57. SYSTSIN variables

Variable Description

CA7INTERFACE(CONSOLE) CONSOLE is the only supported interface

for CA-7 and is the default value for this

variable. Set to NO if you do not use this

interface.

CA7NAME(CA7ONL) The name of the CA-7 control region

address space. Ignored if CA-7 is not

used.

CA7OPTIONS(X’32’) The CA-7 release options. The default is

determined from the CA-7 subsystem

vector table entry and you should not

change it unless directed to do so by IBM

Software Support.

Gateway software components


Table 57. SYSTSIN variables (continued)


CA7SPAN(9999) This variable applies exclusively to the

CA-7 interface. The number represents the

minimum interval (in hours and minutes)

after which it is possible to launch from

Tivoli Workload Scheduler the same job

without specifying a different SCHID. The

default is intentionally set to 9999, an

invalid value, so that it is possible to

distinguish the case where the variable is

not used. If specified, it must be a 4-digit

number in the format HHMM. For

example:

v CA7SPAN(0010) means 10 minutes.

v CA7SPAN(0130) means 1 hour and 30

minutes.

For more details, refer to “Other CA-7

tips” on page 232.

CA7SUBSYSTEM(UC07) The name of the CA-7 subsystem.

CA7USER(CA7CNSL) The user ID that is used to issue CA-7

commands. Ignored if CA-7 is not used.

CA7WAIT(0) The amount of time, in hundredths of a

second, that each gateway task waits after

CA-7 has confirmed that the gateway

request to LOGON to it has been

successfully processed, before issuing the

next command to CA-7. The default is 0,

which means that the next command is

issued immediately. The maximum value

must be less than half the value specified

for MAXWAIT.

SYSTSIN variables




COMPLETIONCODE(LASTSTEP/MAXSTEP) Specifies the job completion code of a JES

multi-step job. This variable can assume

one of the following values:

LASTSTEP

The completion code for a JES

multi-step job is determined by the

last run step in the job. This is the

default value.

MAXSTEP

The completion code is determined by

the highest completion code of any

run step in the job.Any condition code different from 0 in the

last step (if LASTSTEP was selected) or in

any step (if MAXSTEP was selected)

causes the job to be considered

unsuccessfully completed, unless

differently specified using the condcode

option in the job definition in Tivoli

Workload Scheduler.

If a step is flushed, it is not taken into

consideration when determining the

completion code of the job, unless the

flushed step is the last one, in which case

the job is always considered as completed

unsuccessfully.

DEBUG(NO) If set to YES, it causes the gateway to

output diagnostic messages. Use only in

coordination with IBM Software Support.

INTERLINKSUBSYSTEM(ACSS) The name of the subsystem used by

Interlink TCP/IP stack. Ignored if

Interlink is not used as TCP/IP stack.

JESCMDCHR($) The job command recognition character.

The default is set to dollar sign ($) for

JES2 systems and to asterisk (*) for JES3

systems. Change this variable only if a

different command recognition character

is being used.

JESINTERFACE(CONSOLE) CONSOLE is the only supported value for

JES and it is the default value. Set to NO

if you do not use this interface.

MAXWAIT(500) The maximum amount of time, in

hundredths of a second, to wait for a

response to commands. This variable is

ignored if you set both CA7INTERFACE

and JESINTERFACE to NO.

MCSSTORAGE(3) The amount of storage, in megabytes,

used by each extended console used by

the gateway. This variable is ignored if

you set both CA7INTERFACE and

JESINTERFACE to NO.

SYSTSIN variables




OPCINTERFACE(PIF) PIF is the only supported interface for

Tivoli Workload Scheduler for z/OS and

is the default value for this variable. Set to

NO if you do not use this interface.

OPCMSGCLASS(*) The message class for the dynamically

allocated message logs used by Tivoli

Workload Scheduler for z/OS. The

asterisk causes the class to be set to the

same value as EEWSERVE. Ignored if

Tivoli Workload Scheduler for z/OS is not

used.

OPCSUBSYSTEM(OPCS) The subsystem name used for

communications with the Tivoli Workload

Scheduler for z/OS control region.

PEERADDRESS(0:0:0:0:0:0:0:0) The default, 0:0:0:0:0:0:0:0, permits access

by any host. For better security, enter the

IP address of the Workload Scheduler host

of the z/OS extended agent.

Notes:

1. Depending on the Internet Protocol

you are using, specify an IPv4 or IPv6

address by including also the ″.″ (for

IPv4) or ″:″ (for IPv6) between the 0s.

2. If you are migrating from Tivoli


8.2, 8.2.1, or 8.3, ensure that you

modify this variable to comply with

the current format.

3. To connect to an extended agent that

supports only Internet Protocol version

4, you must use IPv4.

PORT(5000) The TCP/IP port number used by Tivoli

Workload Scheduler and the gateway for

communications. This must be the same

as the value entered in the TCP/IP

Address field of the z/OS x-agent

workstation definition.

PUTLINE(YES) When set to YES, it directs trace

information to DDNAME SYSTSPRT.

QLIMIT(2000) The maximum number of messages to be

queued to an extended console.

SUBSYS(UNIS) The prefix used by the extended agent for

z/OS as the first four characters of

extended console names. It is also used as

the first four characters of internal reader

DDNAMES. Change only in coordination

with IBM Software Support.

SVCDUMP(NO) When set to YES, abends cause a SVC

dump. Use only in coordination with IBM

Software Support.

TCPIPSTACK(IBM) The vendor of TCP/IP stack (IBM,

INTERLINK, or OPENCONNECT).

SYSTSIN variables


|||||

|

||||

|||||

|||



TCPNAME(TCPIP) The name of the TCP/IP address space

when the IBM version of TCP/IP stack is

used.

TERMINATOR(X’25’) The transaction termination character. Do

not change the default unless directed to

do so by IBM Software Support.

WTP(NO) When set to YES, it directs trace

information to SYSLOG as

write-to-programmer information. This

can be used if SYSTSPRT does not suit

your needs.

When you use CA-7, PUTLINE(YES) and

WTP(NO) are required if DEBUG(YES).

ZOSV1R2(NO) Set to YES if you are using the JES3

interface with z/OS V1R2 or later. This

parameter is ignored if you are not using

the JES3 interface, because:

v If you are using the JES2 interface, the

level of the operating system does not

make any difference for the product

v If you are using the CA-7 or Tivoli

Workload Scheduler for z/OS

interfaces, the support of z/OS V1R2 or

later is ensured, provided that the

release of the corresponding

subsystem(s) support(s) it.

z/OS gateway version

The version of EEWSERVE (and EEWSPACE) appears in the first line of the EEWSERVE

(and EEWSPACE) log. For example:

EEWTCP10 VERSION RELEASE MODIFICATION LEVEL = VxRyMz

where x is the version, y the release, z the modification level.

SYSTSIN variables


Downloading z/OS gateway fixes from FTP

This section describes how to obtain the files in a fix or fix pack from the IBM

software FTP site.

If a fix or fix pack for Tivoli Workload Scheduler for Applications for z/OS,

version 8.4 is issued by IBM, you can receive it by downloading the files from the

IBM software FTP site.

Download the z/OS gateway fix pack files as follows:

1. Allocate two data sets with LRECL=80 RECFM=80 to hold the downloaded files.

For example:

v TWS4APPS.LOADLIB.L80 (for the load library)

v TWS4APPS.SAMPLIB.L80 (for the samples library)

Use the file characteristics shown in Table 58.

Table 58. File characteristics for obtaining the gateway fix pack files by FTP

Characteristic Value

Organization PS

Record format FB

Record length 80

Block size 27920

1st extent cylinders 1

Secondary cylinders 1

Note: These files are not allocated as type PDS but as regular sequential files.

2. Use FTP to retrieve the LOADLIB and SAMPLES fix pack files from the download

site, by logging in as anonymous, with your e-mail address as the password.

Issue the following commands:

tso ftp ftp.software.ibm.com

anonymous

your_e-mail_address

cd software/tivoli_support/patches/patches_8.4.0/

cd patch_name

cd ZOS

bin

get loadlib_file_name ’TWS4APPS.LOADLIB.L80’ (rep

get samples_file_name ’TWS4APPS.SAMPLIB.L80’ (rep

quit

For example, for fix pack 01 the variables in this list of commands would have

the following values:

patch_name 8.4.0-TIV-TWSWSE-FP0001

loadlib_file_name

LOADLIB_820WSEFP07

samples_file_name

SAMPLES_820WSEFP07

Note: The data set names in quotes on the get commands (the MVS file names)

must match the files that were allocated in step 1.



3. The downloaded files are in an 80-byte packed format. To ensure that the files

have been downloaded correctly, browse them. The beginning of the output

should be similar to the following:

BROWSE TWS4APPS.LOADLIB.L80 Line

\INMR01. ....&......NODENAME......TWSUSR2......A......A......20

....... \INMR02..........IEBCOPY......... ........ ....... .....

..........."8. .... ................TWS84..XAGENT..V8R4M0..FIXPAC04..DRV1511..LO

If it is not, retry the downloads.

4. Receive the downloaded data sets, as follows:

LOADLIB

a. Issue the following command:

TSO RECEIVE INDSN(’TWS4APPS.LOADLIB.L80’)


INMR901I Dataset TWS84.XAGENT.V8R4M0.FIXPAC04.DRV1511.LOADLIB



***

b. Reply:

da(’TWS4APPS.LOADLIB’)

where da means data set and the MVS data set name in quotes is the

name you want for the output loadlib data set.


SAMPLIB

a. Issue the following command:

TSO RECEIVE INDSN(’TWS4APPS.SAMPLIB.L80’)


INMR901I Dataset TWS84.XAGENT.V8R4M0.FIXPAC04.DRV1511.SAMPLIB



***

b. Reply:

da(’TWS4APPS.SAMPLIB’)

where da means data set and the MVS data set name in quotes is the

name you want for the output samplib data set.

Some IEBCOPY messages are displayed as the library is uncompressed.After receiving the files, the file characteristics change to those shown in

Table 59.

Table 59. File characteristics for the LOADLIB file after receiving it


Data Set Name TWS4APPS.LOADLIB

Organization PO

Record format U

Record length 0

Block size 32760

1st extent blocks 10



Table 59. File characteristics for the LOADLIB file after receiving it (continued)


Secondary blocks 5

Data set name type PDS

Table 60. File characteristics for the SAMPLIB file after receiving it


Data Set Name TWS4APPS.SAMPLIB

Organization PO

Record format FB

Record length 80

Block size 27920

1st extent blocks 4

Secondary blocks 1

Data set name type PDS

Configure the downloaded fix pack files as described in “Configuring” on page

210.

Locating product support

To find the Tivoli Workload Scheduler for Applications support page, see the

appendix on support information in Tivoli Workload Scheduler: Troubleshooting Guide.

Use the Search Support option to search for items of interest to you. Useful terms

to enter for Tivoli Workload Scheduler for Applications for z/OS are: ″TWS4APPS″,

message IDs, ABEND codes, ″EEWSERVE″, ″MVS xagent″, ″TWS applications

z/OS″, or the interface types ("TWS for z/OS", CA-7, JES2, JES3).



Chapter 26. Configuring the z/OS access method

Tivoli Workload Scheduler launches jobs on an extended agent for z/OS

workstation. The extended agent for z/OS is defined in a standard Tivoli Workload

Scheduler workstation definition, which gives it a name and identifies the access

method to be used. The extended agent for z/OS workstation is a workstation

definition linked to an instance of the z/OS system.

To launch a job on an extended agent for z/OS workstation, Tivoli Workload

Scheduler runs the access method, passing it information about the job. The access

method communicates with the instance of the z/OS host and monitors the job

through completion, writing job progress and status information to the job’s

standard list file.

This chapter describes how to:

v Define the options for the z/OS method. See “Defining the configuration

options.”

v Define an extended agent for a z/OS job. See “Defining jobs in z/OS” on page

222.

v Schedule an extended agent for a z/OS job. See “Defining z/OS jobs in Tivoli

Workload Scheduler” on page 223.

See Chapter 4, “Defining extended agent workstations,” on page 47 to learn how to

define an extended agent workstation in Tivoli Workload Scheduler.


Every installed instance of the z/OS access method must have a matching options

file. You can create it during or after the installation of the access method with

either the Option Editor (see Chapter 3, “Setting options with the Option Editor,”

on page 43) or any common text editor.

The options file must reside on the Tivoli Workload Scheduler hosting computer

for the extended agent in the TWShome\methods directory. If you do not create one,

the agent uses by default one of the global options file (either mvsca7.opts,

mvsjes.opts, or mvsopc.opts).

Table 61 on page 222 describes the options that you can define for the z/OS access

method.


||||

Table 61. Tivoli Workload Scheduler for Applications for z/OS access method options

Options File Entries Description

BLOCKTIME=min (Optional) Defines the amount of time, in minutes, the

method will wait for a response to a status check before

timing out. This value must be less than the value of

CHECKINTERVAL (described below) and of Tivoli

Workload Scheduler’s local option bm check status.

Fractional values are accepted; for example, .5 for 30

seconds, or 1.5 for one minute and 30 seconds. The default

is 2.

Note: Only change this option from the default value if

specific network problems cause delays in the transmission

of data from the z/OS gateway.

CHECKINTERVAL=min (Optional) Defines the polling rate, in minutes, for checking

the status of z/OS jobs that were launched by the method.

Fractional values are accepted; for example, .5 for 30

seconds, or 1.5 for one minute and 30 seconds. The default

is 2.

When checking non-Tivoli Workload Scheduler-launched

jobs on z/OS that are used as dependencies, the method

uses the Tivoli Workload Scheduler local option bm check

status instead of CHECKINTERVAL to determine its

polling rate.

CFUSER=name (Optional

1) Assigns the user name used by the access

method to check file dependencies (CF tasks). It can be the

same as LJUSER.

GSUSER=name (Optional


method to check non-Tivoli Workload Scheduler-launched

jobs on z/OS that are used as dependencies (GS tasks). The

default is root.

LJUSER=name (Optional


method to launch jobs (LJ tasks). This must be a valid

UNIX or Windows user who submits local jobs and is able

to connect to the Tivoli Workload Scheduler z/OS gateway

on the z/OS system. The default is the login parameter in

the job definition.

RETRYCOUNT=count (Optional) Defines the number of times a status check is

attempted before Tivoli Workload Scheduler writes a

timeout message to a job’s stdlist file, and marks it in the

abend state. For details, see options CHECKINTERVAL

and BLOCKTIME. The default is 10.

Notes:

1. For best results, allow LJUSER, CFUSER, and GSUSER to take the default

values. On the mvsca7 gateway, the CA7USER ID is not related to LJUSER,

CFUSER, and GSUSER.

Defining jobs in z/OS

In z/OS, jobs that are scheduled with Tivoli Workload Scheduler are defined as

described in the following sections:

v “For JES jobs:” on page 223

v “For CA-7 jobs:” on page 223

v “For Tivoli Workload Scheduler for z/OS jobs:” on page 224

Defining the z/OS configuration options


Defining z/OS jobs in Tivoli Workload Scheduler

Tivoli Workload Scheduler job definitions are required for each z/OS job you

intend to schedule and launch with Tivoli Workload Scheduler. They are defined

like other Tivoli Workload Scheduler jobs and include job name, user name, special

script name options, and optional recovery options.

Remember that you should include neither special characters, other than dash (-)

and underscore (_), nor national characters in the Tivoli Workload Scheduler job

name. Such characters are not supported in z/OS, and when the Tivoli Workload

Scheduler job is passed to z/OS by the access method, z/OS rejects the name and

abends the job if it finds them.

See Chapter 5, “Defining extended agent jobs,” on page 53 for reference.

Task definition syntax for z/OS jobs scheduled with Tivoli

Workload Scheduler

The following are descriptions of the task definition syntax (command line

“scriptname”) for z/OS jobs that Tivoli Workload Scheduler schedules and

launches from extended agent workstations using the mvsjes (JES2/3 jobs), mvsca7

(CA-7 jobs), or mvsopc ( IBM Tivoli Workload Scheduler for z/OS jobs) methods.

You specify these task string parameters in the following places when you define


v In the Command field of the Task page of the Properties - Job Definition

Window, if you use the Job Scheduling Console.





environment.

For JES jobs:

The syntax is:

dataset [<|= condcode]

where:

dataset Specifies the JES job data set or the name of a member of a

partitioned data set.

condcode Specifies the condition code that indicates successful job

completion. If preceded by <, the condition code must be less than

or equal to this value. If preceded by =, the condition code must be

equal to this value. If omitted, “= 0000” is used. Note that there

must be a space on both sides of the operator (< or =).

Example:

gold.apayable.cntl(apayjob1) = 0004

For CA-7 jobs:

The syntax is:

jobname [SCHID(nnn)] [CC(nnnn)] [...]

[RO(EQ|LT|GT|GE|LE|NE|#S|IG|NO) ]

[SET(SKP|NTR|NDB) ]

Defining z/OS jobs in Tivoli Workload Scheduler

Chapter 26. Configuring the z/OS access method 223

where:

jobname The name of the job in CA-7.

SCHID The schedule ID (a number 1-255) to be assigned to the job.

CC The condition code used with RO that indicates successful job

completion.

RO The relational operator for condition code CC.

SET Sets job options to skip the next scheduled run (SKP), disable

normal job triggering (NTR), or bypass database loading on

completion (NDB).

For complete descriptions of the parameters, refer to the CA-7 Commands Guide.

Example:

ARCVJOB SCHID(203) CC(0001) RO(EQ) SET(NDB)

For Tivoli Workload Scheduler for z/OS jobs:

The syntax is:

appl [IA(yymmddhhmm)|IATIME(hhmm)] [...]

[DEADLINE(yymmddhhmm)|DEADLINETIME(hhmm)]

[PRIORITY(pri)]

[CPDEPR(Y|N|P|S)]

where:

appl The name of the Tivoli Workload Scheduler for z/OS application to

be inserted into the current plan.

IA The input arrival date and time in the form: yymmddhhmm.

IATIME The input arrival time in the form: hhmm.

DEADLINE The deadline arrival date and time in the form: yymmddhhmm.

DEADLINETIME

The deadline arrival time in the form: hhmm.

PRIORITY The priority (1-9) at which to run the application.

CPDEPR The current plan dependency resolution selection.

Y Add all successor and predecessor dependencies.

N Do not add any dependencies, (the default.)

P Add predecessor dependencies.

S Add successor dependencies.

For complete descriptions of the parameters, refer to the Tivoli Workload Scheduler

for z/OS documentation.

Example:

PREFABJOB44 IA(0202181000) PRIORITY(5) CPDEPR(Y)

Task definition syntax for z/OS jobs


Task definition syntax for other z/OS jobs

The following are descriptions of the task definition syntax (command line

“scriptname”) for z/OS jobs that are to be monitored for completion. The

completion of these z/OS jobs can be used as “follows” dependencies for Tivoli

Workload Scheduler-launched jobs. The jobs to be monitored can be JES, CA-7, or

Tivoli Workload Scheduler for z/OS.

Tivoli Workload Scheduler monitors these jobs until their status changes to success.

The details of the outcome of such jobs must be checked in the subsystem where

the jobs were launched. Tivoli Workload Scheduler only records whether or not

these jobs completed successfully. To find the reason for the failed submission or

completion of one of these jobs, or to check for dependency failures, work with the

host subsystem operator who can obtain this information from the EEWSERVE log.

The basic syntax is:

tws-job follows xagent::"mvs-job"

where:

tws-job The name of the Tivoli Workload Scheduler job that depends on

the completion of the specified z/OS job.

xagent The name of the Tivoli Workload Scheduler extended agent

workstation associated with the scheduler of the z/OS job, that is,

an extended agent defined with the mvsjes, mvsca7, or mvsopc

method. The two colons (::) are a required delimiter.

mvs-job The identification of the z/OS job. This string must be enclosed in

quotation marks. See the syntax descriptions below.

For JES jobs:

The syntax is:

"jobname[<|= condcode]"

where:

jobname The name of the job in JES.

condcode The condition code that indicates successful job completion. If

preceded by <, the condition code must be less than or equal to

this value. If preceded by =, the condition code must be equal to

this value. If omitted, “= 0000” is used. There must be a space on

both sides of the operator (< or =).

Example:

job5 follows jesworkstation::"apayable = 0004"

For CA-7 jobs:

The syntax is:

"jobname [SCHID(nnn)] [...]"

[DATE(*|*yyddd)}]

[SPAN( {* })]

{scope}

{date}

{(startdate,starttime,scope)}

{(startdate,starttime,enddate,endtime)}

where:

Task definition syntax for other z/OS Jobs


jobname The name of the job in CA-7.

SCHID The schedule ID (a number 1-255) of the job.

DATE A specific log date to be searched for the job.

SPAN The span of log records to be searched for the job.

For complete descriptions of the parameters, refer to the CA-7 Commands Guide.

For example:

joba follows workstation::"arcvjob schid(203) span(12)"

See also “Other CA-7 tips” on page 232.

For Tivoli Workload Scheduler for z/OS jobs:

The syntax is:

"application[IA(yymmddhhmm)|IATIME(hhmm)][...]"

[JOBNAME(jobname)]

[OPNO(num)]

where:

application The name of the Tivoli Workload Scheduler for z/OS application

(job stream) in the current plan.

IA The input arrival date and time.

IATIME The input arrival time.

JOBNAME The z/OS job name.

OPNO The operation number (1-255). If included, the application is

considered completed when it reaches this operation number.

For complete descriptions of the parameters, refer to the Tivoli Workload Scheduler

for z/OS documentation. For example:

joba follows twsworkstation::"PREFABJOB44 IA(0202181000) JOBNAME(PFJ3)"

Operational considerations for the EEWSERVE gateway task

The following considerations apply:

EEWSERVE not running

If the EEWSERVE task on the mainframe is not running, and a Tivoli Workload

Scheduler job with no follows dependency is submitted from the extended

agent, the job will show an error status and will fail, that is, the job will not run

after the EEWSERVE task is started. However, if a Tivoli Workload Scheduler

job has a follows dependency for an external (non-Tivoli Workload Scheduler)

job which runs under JES, Tivoli Workload Scheduler for Applications for z/OS

or CA-7, the internal check job (CJ) command is reissued after EEWSERVE is

started. The extended agent workstation still shows its status as linked even if

EEWSERVE is not running.

For this reason, if a z/OS automation product such as NetView is available on

the mainframe, a rule should be written to detect any outages of the

EEWSERVE task.

Instance limitations in LPARs

Due to the ENQ/DEQ mechanism in use, only one instance of the EEWTCP02

task (default name EEWSPACE) can be run on a z/OS LPAR. If a second

instance is started, it will fail with RC=04. So even if you use different started



task names and PORT numbers, only one instance of EEWSPACE or

EEWSERVE can exist concurrently on a z/OS LPAR.

File (OPENS) dependencies syntax on z/OS files

Tivoli Workload Scheduler jobs and job streams can use z/OS files as

dependencies. The basic syntax is:

tws-job opens xagent#"hlq1.hlq2.hlq3"

where:

tws-job The name of the Tivoli Workload Scheduler job dependent on the

specified z/OS file.

xagent The name of the Tivoli Workload Scheduler extended agent

workstation associated with the scheduler of the z/OS job, that is,

an extended agent defined with the mvsjes, mvsca7, or mvsopc

method.

Note: The # sign is a required delimiter.

hlq1.hlq2.hlq3 The identification of the z/OS file in high level qualifier terms.

Note: This string must be enclosed in quotation marks.

For more information, see “Checking for files on z/OS” on page 234.




Chapter 27. Reference information

This chapter describes job states when operating on JES, CA-7, and Tivoli

Workload Scheduler for z/OS in the Tivoli Workload Scheduler environment.

Technical overview

The z/OS gateway uses an extended MCS console to communicate with JES and

CA-7. The program issues the MCSOPER macro to activate an extended MCS console.

The z/OS gateway is then able to receive messages and command responses by

issuing the MCSOPMSG macro, and can issue commands by issuing the MGCRE macro.

All the return codes from the extended MCS macros are handled as documented in

IBM z/OS Programming: Authorized Assembler Services Reference, Volume 3, SA22-7611.

Managing JES jobs

The following sections describes how to manage JES jobs.

Launching JES jobs

To launch and monitor a JES job, Tivoli Workload Scheduler passes the name of the

JCL data set or partition data set it wants to run to the z/OS gateway, which, in

turn, submits it to JES. Submissions occur using dynamically allocated internal

readers in JES. The gateway allocates an internal reader at the start of each task

and then submits the job to the reader.

When a job is submitted, the job name and JES job ID are also entered in the

Tablespace. When an SMF record containing relevant job scheduling data is passed

through the IEFU84 exit, the job and condition code information are made

available to Tivoli Workload Scheduler. Because Tivoli Workload Scheduler keeps

track of both the job name and the JES job ID, it is able to check for the specific job

it submitted. (Currently the Gateway uses Type 30 SMF records and also subtypes

1,4,5.)

Tivoli Workload Scheduler checks submitted jobs periodically to see if they are

active. If a Tivoli Workload Scheduler-submitted job is not active and no

information about it is found through the IEFU84 exit, the job is marked as abend

in Tivoli Workload Scheduler displays. This situation might occur if a job fails for

security reasons or JCL syntax problems.

JES job states: Table 62 lists JES job states with respect to Tivoli Workload

Scheduler.

Table 62. JES job states with respect to Tivoli Workload Scheduler

Tivoli Workload

Scheduler Job

State JES Job State Comment

intro Not available Tivoli Workload Scheduler is starting the

method.

wait Queued Job is queued.

wait Not available If the job remains in this state, it might be due

to a security violation in z/OS. Check the job

on the z/OS system.


Table 62. JES job states with respect to Tivoli Workload Scheduler (continued)

Tivoli Workload

Scheduler Job

State JES Job State Comment

exec Executing Job is running.

succ Completed Job’s condition code meets the completion

criteria in the Tivoli Workload Scheduler job

definition.

abend Completed Job condition code does not meet the

completion criteria in the Tivoli Workload

Scheduler job definition, or a system or user

abend has occurred. System abend codes, in

hexadecimal, are prefixed with ″S″, and user

abend codes, in decimal, are prefixed with ″U″.

Both types of code are written to the job stdlist

file.

extrn Not available Status unknown. Can occur only when checking

a job that is used as a dependency.

Monitoring JES jobs

The details of the outcome of JES jobs must be requested from the subsystem

where these jobs were launched. From Tivoli Workload Scheduler you should only

expect to find out whether these jobs completed successfully or not. To find the

reason for a failed submission or failed completion of one of these jobs or to check

for dependency failures, the Tivoli Workload Scheduler operator should work with

the host subsystem operator who can obtain this information from the EEWSERVE

log.

Checking JES jobs

To check a JES job that was not launched by Tivoli Workload Scheduler, the name

of the job is passed by Tivoli Workload Scheduler to the gateway. Because Tivoli

Workload Scheduler did not submit the job, the JES job ID is not available. The

Gateway enters the name in the Tablespace, and waits for information about the

job to appear in SMF records passed through the IEFU84 exit.

The IEFU84 exit cannot handle every job without impacting the performance of the

entire system because it is invoked for each job running on the z/OS system.

v If the job is not present in the gateway dataspace, the IEFU84 exit does not

perform any action.

v If the job is submitted by Tivoli Workload Scheduler, the gateway inserts the job

into the dataspace. In this case the IEFU84 exit monitors the status of the job and

of each step contained in the job.

v If the job is not submitted by Tivoli Workload Scheduler, the gateway inserts the

job into the dataspace only if the gateway receives a request from Tivoli

Workload Scheduler to check its status because the job represents an

internetwork dependency.

To have the internetwork dependencies of a z/OS job correctly handled by Tivoli

Workload Scheduler on the z/OS system, ensure that there are no occurrences of

the z/OS job in any job queue including the output queue. If any occurrences of

the z/OS job are present then purge them. The internetwork dependencies of a

z/OS job are handled by Tivoli Workload Scheduler in the following ways:

v If there are no occurrences of z/OS jobs in the job queues, the gateway inserts

the job into the dataspace the first time it receives the request from Tivoli

Launching JES jobs


Workload Scheduler to check the job status. The gateway inserts the job into the

dataspace with an unknown job ID ready to be monitored.

v When the z/OS job is submitted, the IEFU84 exit finds the job in the dataspace

and updates the corresponding entry with the JES job ID. From now on the

z/OS job is monitored using the associated JES job ID. If the job completes

successfully, the gateway returns the information to Tivoli Workload Scheduler,

and the internetwork dependency is correctly resolved.

Managing CA-7 jobs

The following sections describe how to manage CA-7 jobs.

Launching CA-7 jobs

To launch and monitor a CA-7 job, Tivoli Workload Scheduler passes the job name,

and optionally the CA-7 sched ID, it wants to run to the z/OS Gateway. At the

time of the submission request, the gateway receives the CA-7 job number, which

is used to track all subsequent activity for the job. It is important to note that CA-7

itself must be authorized to accept commands from the console for this mechanism

to work. For more information about this feature, refer to the CA-7 documentation

for a description of the Modify and Login commands.

CA-7 job states

Table 63 lists CA-7 job states with respect to Tivoli Workload Scheduler.

Table 63. CA-7 job states with respect to Tivoli Workload Scheduler

Tivoli Workload

Scheduler Job

State CA-7 Job State Comment

intro Not applicable Workload Scheduler is starting the method.

wait Ready Queue The job is queued.

exec Active Queue The job is running

succ Completed The job condition code meets the completion

criteria in the Tivoli Workload Scheduler job

definition.

abend Request Queue Request queue as result of an abend.

extrn Not applicable Status unknown. Can occur only when checking a

job that is used as a dependency. Also see note

below.

Note: If a job remains in the abend or extrn states, it might be due to a security

violation in z/OS. Check the job on the z/OS system.

Checking CA-7 jobs

To check a CA-7 job that was not launched by Tivoli Workload Scheduler, the

name of the job, and optionally the CA-7 sched ID, is passed by Tivoli Workload

Scheduler to the gateway. To see if the job is currently being scheduled or run by

CA-7, the gateway searches the following CA-7 queues, in this order: Request

Queue, Ready Queue, and Active Queue. If the job is not found, Tivoli Workload

Scheduler rechecks at a rate defined by the bm check status value in its local

options file.

Monitoring JES jobs


Other CA-7 tips

v When using CA-7, the CA7USER must be a CA-7 ID that is authorized to issue

demand commands from the MVS console (MODIFY CA7,DEMAND,JOB=XXXXXXXXX).

v The limitation that in prior versions of the product forced users to uniquely

identify occurrences when defining CA-7 jobs in Tivoli Workload Scheduler (that

is, by adding either or both the SCHID and SPAN operands) has now been

removed through the new initialization parameter CA7SPAN.

The logic behind the implementation of CA7SPAN is the following: if SPAN is

specified in the Tivoli Workload Scheduler definition of a job, then CA7SPAN is

ignored. If SPAN is not specified (or cannot be specified, as in the case of jobs

launched by Tivoli Workload Scheduler), then CA7SPAN is taken into

consideration and its value is used in the inquiries to CA-7 as SPAN. This

circumvents the limitation according to which each occurrence must be uniquely

identified and makes it possible to launch from Tivoli Workload Scheduler the

same job with the same SCHID, the only condition being that the interval

between two submissions must be greater than the value specified with

CA7SPAN.

It is important to know that, if specified, the value of CA7SPAN will be used in

all the inquiries to CA-7 (if they refer to jobs launched by Tivoli Workload

Scheduler or if they are issued to check internetwork dependencies for jobs not

launched by Tivoli Workload Scheduler) except for those jobs that have SPAN

specified in their Tivoli Workload Scheduler definition.

It is good practice to have the CA7SPAN (or SPAN) greater than

RetryCount*CheckInterval.

v If you run products, such as AFOPER, that suppress console messages, make

sure that they do not suppress CA-7 messages.

v Ensure that any MPFLSTxx member used (or any suppression product) does not

suppress the following message IDs:

CA-7*

SPO7*

SLIF*

nn* (where nn are the last two digits of the calendar year)

Notes:

1. If the .NO_ENTRY parameter of MPFLSTxx has SUP(YES), then all of the

above message IDs must appear in the MPFLSTxx member with SUP(NO).

The previous configuration with SUP(YES) AUTO(YES) is no longer valid.

2. Messages in the format nn* are included because some of the messages

issued in response to a CA-7 LRLOG command have no message ID other

than the Julian date.

Managing Tivoli Workload Scheduler for z/OS jobs

The following sections describes how to manage Tivoli Workload Scheduler for

z/OS jobs.

Launching Tivoli Workload Scheduler for z/OS jobs

To launch and monitor a Tivoli Workload Scheduler for z/OS job, Tivoli Workload

Scheduler passes the application name, and other optional parameters, it wants to

run to the z/OS Gateway. If it exists in the Tivoli Workload Scheduler for z/OS

database, the application is inserted into the current plan. The input arrival,

deadline arrival, priority, and automatic dependency resolution parameters, if

included, override any values specified in Tivoli Workload Scheduler for z/OS.

Checking CA-7 jobs


At a rate defined by the CheckInterval value in the method options file, Tivoli

Workload Scheduler checks the status of the occurrence (application) in Tivoli

Workload Scheduler for z/OS.

Tivoli Workload Scheduler for z/OS operation states

Table 64 lists Tivoli Workload Scheduler for z/OS operation states with respect to


Table 64. Tivoli Workload Scheduler for z/OS operation states with respect to Tivoli

Workload Scheduler

Tivoli Workload Scheduler Job

State Tivoli Workload Scheduler for z/OS Operation State

wait pending

wait undecided

wait wait

wait ready

exec started

succ complete

abend interrupted

abend error

abend deleted

abend Not applicable

extrn Not applicable

Tivoli Workload Scheduler for z/OS occurrence states

Table 65 lists Tivoli Workload Scheduler for z/OS operation occurrence states with

respect to Tivoli Workload Scheduler.

Table 65. Tivoli Workload Scheduler for z/OS operation occurrence states with respect to



Job Stream State Tivoli Workload Scheduler for z/OS Occurrence State

wait pending

wait undecided

exec started

succ complete

abend error

abend deleted

abend Not applicable

extrn Not applicable. Status unknown. Can occur only when

checking a job that is used as a dependency.

Checking Tivoli Workload Scheduler for z/OS jobs

To check a Tivoli Workload Scheduler for z/OS job that was not launched by Tivoli

Workload Scheduler, the name of the application, and optionally the operation, is

passed to the gateway. A check is made to see if the occurrence or operation is in

the current plan. If it is not found, Tivoli Workload Scheduler rechecks at a rate

defined by the bm check status value in its local options file.

Managing Tivoli Workload Scheduler for z/OS jobs


Checking for files on z/OS

The existence of a file can be used as a job dependency in Tivoli Workload

Scheduler. To check for the existence of a file on z/OS, Tivoli Workload Scheduler

passes the file name to the Gateway. The file name is allocated with DISP=OLD,

and is considered to exist if the following conditions apply:

v The data is cataloged

v It is allocated

v It is not being used by another task

If the data set does not exist, Tivoli Workload Scheduler continues to wait and

check for the file at a frequency determined by the bm check file option in the

localopts file of the fault-tolerant workstation that is hosting the extended agent.

The localopts options are described in the Tivoli Workload Scheduler: Planning and

Installation Guide.

Note: Tivoli Workload Scheduler can only use fully qualified data set names for

non-partitioned files. If a Generation Data Group name is to be used, it must

be the fully qualified name and not a relative name (for example,

xxxxx.xxxxx(-1) cannot be used).

Timing considerations

When Tivoli Workload Scheduler checks dependencies on z/OS jobs not launched

by Tivoli Workload Scheduler for Applications, certain timing issues are critical to

ensuring that any associated job dependencies are correctly resolved. For the

correct resolution of these external dependencies, Tivoli Workload Scheduler must

attempt to resolve the dependency at least once before the z/OS job is submitted.

After the z/OS job has been submitted and has successfully completed, the next

periodic check of the dependency by Tivoli Workload Scheduler is able to manage

the dependency.

External dependencies are checked by Tivoli Workload Scheduler in the following

circumstances:

v If the external dependency on a Tivoli Workload Scheduler for Applications

z/OS job is the only dependency in the job, the dependency is checked

immediately after the plan is generated or extended. However, as the plan might

have a period of several days, weeks, or months, this might not be very

frequently.

v Subsequently to the first check, the dependency is checked with a frequency

determined by the Tivoli Workload Scheduler configuration parameters.

v If the external dependency is preceded by another dependency, the external

dependency will not be checked until the other dependency is resolved.

Thus, when creating external dependencies in Tivoli Workload Scheduler on Tivoli

Workload Scheduler for Applications z/OS jobs, you should schedule the job so

that the first dependency check takes place before the z/OS job is submitted.

If this synchronization is not taken into account, Tivoli Workload Scheduler might

wait indefinitely to resolve a job dependency. A similar problem can occur as the

result of a communication failure between the z/OS and Tivoli Workload

Scheduler environments that prevents Tivoli Workload Scheduler from determining

the status of a z/OS job to satisfy a job dependency.

Checking for files on z/OS


Diagnostic information

z/OS jobs submitted by Tivoli Workload Scheduler can fail to complete for a

number of reasons. The step in the submission process in which a job fails

determines how much information is available and is provided by Tivoli Workload

Scheduler as follows:

v If a job fails before it is actually initiated (usually the result of a JCL or security

problem), Tivoli Workload Scheduler recognizes that it no longer exists, and

marks it as abended in Console Manager (Conman) displays. No further

information is provided.

v If a job fails after being started, Tivoli Workload Scheduler:

1. Obtains its condition code and user abend code, if any

2. Writes them to the job standard list file

3. Marks the job as abend in Console Manager (Conman) or Job Scheduling

Console displays

Job standard lists can be displayed with the Console Manager (Conman) and

with the Job Scheduling Console.

Troubleshooting

To assist in troubleshooting, ensure the JES log is obtained for the EEWSPACE and

EEWSERVE started tasks. This will help in determining the context in which a

message was issued. Depending on the job scheduling interface you use, additional

helpful information might be obtained from other logs. For example, if you use

CA-7, you should obtain the following:

v The CA-7 log

v The console log for the interval covering the test period

v The job log of the job resulting in error (if this is the case)

v The UNIX script file related to that job

Diagnostic information


Troubleshooting for z/OS


Part 6. Common serviceability



Chapter 28. The return code mapping feature

The return code mapping feature provides a standard way of mapping messages

into return code values. You can also customize the return code mapping. This

feature is available for the following access methods:


v PeopleSoft

v SAP R/3

The return code mapping feature provides more granularity when defining the

success or failure policies of jobs and improved flexibility in controlling job

execution flows based on execution results. Job return code mapping provides the

following capabilities:

v Users can define a job final status (successful or failed) based on a condition on

the return code of the execution of the program or script of the job.

v The return code can be provided also to the recovery job that is associated with

it in the job definition. This causes the recovery job to perform different

processing based on the return code.

Creating a return code mapping file

You can create a return code mapping file to customize your own return codes

with respect to certain conditions that might affect a job when it runs. Use this file

to set the success condition of the job, which Tivoli Workload Scheduler uses to

assess if the job completes successfully or in error. The return code is sent to Tivoli

Workload Scheduler in the form of a %RC nnnn message. If this message is received,

the job state is updated accordingly.

Each method has its own set of files to map the messages into return code values.

The mapping files can be either global or local for a workstation.

Return code mapping files that are specific to a workstation are named according

to the following scheme:

TWShome/methods/rcm/<method_name>-<type>-<workstation>.rcm

Global mapping files have a file name according to the following scheme:

TWShome/methods/rcm/<method_name>-<type>.rcm

For the Oracle E-Business Suite and PeopleSoft access methods, type is always

equal to rcmap. For the SAP R/3 access method, type is as described in “Return

code mapping file names for r3batch” on page 244.

Syntax

Use the following syntax to create the return code mapping file:

[#] “pattern1” “pattern2”...“patternn” = RC value

Parameters

# Optional comment. All the lines starting with this symbol (#) are

not used for mapping.

patternn Pattern strings delimited by double quotes (“ and ”). If you use


only one pattern string, you can omit the double quotes. If the

pattern string contains a double quote character, then it must be

escaped by backslash (\). The string can contain the following

wildcards and special characters:

Asterisk (*)

Matches an arbitrary number of characters.

Question mark (?)

Matches a single character.

Backslash (\)

Escape character.

RC value The return code value. This value is sent by the method to Tivoli

Workload Scheduler by a %RC nnnn message.

Examples

The following is an example of a return code mapping file. The line numbers in

bold do not belong to the file, but are shown for reference:

1. # This is an RC mapping file for joblog.

2.

3. “User * missing ” = 102

4. “\*\*\*” = 103

5. “User \

6. * \

7. missing” = 102

In this example:

v Line 1 is a comment and is not used for mapping.

v Line 2 is blank and is ignored. All blanks preceding or following a pattern string

are ignored, as well as those between the equals sign and the return code value.

v Line 3 matches every message starting with the string User and ending with the

string missing.

v Line 4 matches every message starting with three asterisks (*) followed by a

blank. When you use the asterisk in this way and not as a wildcard, you need to

escape it with a backslash.

v Lines 5 through 7 contain a pattern taking several lines. It matches the same

messages as the pattern of line 3.

Considerations

Note the following facts:

v The order of the pattern lines is important as the first matching pattern line is

used to build the return code value.

v Empty pattern strings (“”) are ignored by the pattern matching procedure.

For example, the following is a valid pattern sequence. The first line is more

restrictive than the second line.

“625” “User * missing” = 104

“” “User * missing” = 102

The following pattern sequence is formally valid, but the second pattern line is

never used. Because the first line is more general, it is always matched first.

“” “User * missing” = 102

“625” “User * missing” = 104

Return code mapping file syntax


Return code mapping for psagent and MCMAGENT

For the Oracle E-Business Suite and PeopleSoft access method, you can write

return code mapping files associating the internal states listed in Table 66 and

Table 67.

When no return code mapping files are defined, or when a string returned by the

access method does not satisfy any of the matching patterns of the mapping file,

the access method uses the respective standard return codes listed in the tables.

Table 66. Job states and return codes for the Oracle E-Business Suite access method

MCMAGENT job state MCMAGENT return code

″RUNNING″ 1

″PENDING″ 2

″COMPLETE″ 3

″INACTIVE″ 4

″NORMAL″ 5

″TERMINATING″ 6

″PAUSED″ 7

″RESUMING″ 8

″STANDBY″ 9

″SCHEDULED″ 10

″WAITING″ 11

″WARNING″ 13

″ERROR″ 14

″TERMINATED″ 15

″DELETED″ 16

″ON HOLD″ 17

″DISABLED″ 18

″NO MANAGER″ 19

″SUSPENDED″ 20

″TEST FAILURE″ 21

″NOT FOUND″ 22

Table 67. Job states and return codes for the PeopleSoft access method

psagent job state psagent return code

″CANCEL″ 1

″DELETE″ 2

″ERROR″ 3

″HOLD″ 4

″QUEUED″ 5

″INITIATED″ 6

″PROCESSING″ 7

″CANCELED″ 8

″SUCCESS″ 9


Chapter 28. The return code mapping feature 241

Table 67. Job states and return codes for the PeopleSoft access method (continued)

psagent job state psagent return code

″NO SUCCESSPOSTED″ 10

″POSTED″ 11

″NOT POSTED″ 12

″RESEND″ 13

″POSTING″ 14

″GENERATED″ 15

Examples

The extended agent for Oracle E-Business Suite returns the TERMINATED string. The

resulting return code depends on the following conditions:

v No return code mapping file exists. In this case, the method sends a return code

value of 15, as listed in Table 66 on page 241.

v A return code mapping file exists and is:

"NORMAL"=0

"TERMINATED","DELETED"=1

In this case, the access method finds the matching pattern and sends a return

code value of 1 as listed in Table 66 on page 241.

v The return code mapping file is:

"NORMAL"=0

"ERROR","DELETED"=1

In this case, the access method does not find the matching pattern and sends a

return code value of 15 as listed in Table 66 on page 241.

Return code mapping for r3batch

Using return code mapping with r3batch can be useful in overcoming differences

in the return code mechanisms of R/3, which returns a mixture of messages and

numbers, and of Tivoli Workload Scheduler, which handles exclusively numeric

return codes. By customizing the return code mapping files listed in “Return code

mapping file names for r3batch” on page 244, you can map messages from R/3

logs, spool lists, and exceptions from RFC function modules into return code

values that Tivoli Workload Scheduler can handle.

Note that when you do not use this feature, r3batch does not send any return

codes to Tivoli Workload Scheduler. In this case, Tivoli Workload Scheduler

displays only the r3batch exit code, which cannot be used to set up rccondsucc

conditions.

The return code mapping mechanism works as follows:

1. r3batch reads the output retrieved from the R/3 system (R/3 job log, process

chain log, spool list, and so on appended to the stdlist of the related Tivoli

Workload Scheduler job).

2. Following your specifications in the rcm files, the R/3 return messages or codes

are mapped into your custom return codes and passed on to Tivoli Workload

Scheduler.

3. These return codes are used together with the rccondsucc keyword set in the

extended agent job definition and handled accordingly. Return code mapping is



meaningful only if you use the return codes to write the expressions that

determine job completion. Conversely, in the case of this extended agent, the

use of rccondsucc is significant only if Tivoli Workload Scheduler gets return

codes (not exit codes) from the access method.

To use the return code mapping feature:

v Leave the value of the rcmap option as ON (this is the default).

v Depending on which R/3 logs you want r3batch to read and map, leave the

default settings of the retrieve_joblog, retrieve_pchainlog, and

retrieve_spoollist options as ON and manually create the corresponding rcm

files.

v If you want to map messages from the R/3 syslog, set the log_r3syslog option

to ON and manually create the corresponding rcm file.

When setting up your return code mapping for r3batch, consider the following:

v You can define any return code numbers for your use because there are no

reserved return codes for the access method or for Tivoli Workload Scheduler.

v Mapping files are scanned sequentially: the first match found performs the

corresponding mapping. When you define a mapping file, write the most

restrictive strings first.

v When you define a mapping file, remember that the R/3 log messages are read

in their entirety. If you want to map only a part of the entry, you must use the

wildcard characters.

v If two lines match two different patterns, then the return code is set to the

higher value. In general the return code is set to the highest value among the

ones yielded by the matched patterns. This is shown in the following example:

The job log returned after job PAYT410 has run is:

*** ERROR 778 *** EEWO0778E Failed to modify the job PAYT410 with job id

*** 05710310.

*** ERROR 176 *** EEWO0176E Failed to add step 1.

*** ERROR 552 *** EEWO0552E The R/3 job scheduling system has found an

*** error for user name * and job name PAYT410. Please check R/3

*** syslog.

*** ERROR 118 *** EEWO0118E Execution terminated. Could not create and

*** start an instance of the R/3 batch job.

ERROR LEVEL=118

and the system log contains the following line:

|011:05:12|MAESTRO|SAPMSSY1|EFT|> Step 1 contains illegal values

The r3batch-joblog.rcm file contains the following matching line:

"118""*"=100

while the r3batch-syslog.rcm file contains the following matching line:

"*MAESTRO*Step 1 contains illegal values"=9999

In this case, the return code sent back to Tivoli Workload Scheduler is 9999

because it is the higher of the two matching patterns.

v If no matching takes place, no return code is sent to Tivoli Workload Scheduler.

Return code mapping for r3batch


Return code mapping file names for r3batch

r3batch uses the global return code mapping files listed below. You must manually

create the rcm directory under TWShome/methods and the mapping files you want to

implement.

TWShome/methods/rcm/r3batch-joblog.rcm

Maps messages from the R/3 job log of a job into return code values. If this file

is not present, the messages in the joblog are ignored.

The format of the mapping file is:

<message text pattern>

[<program pattern>[<message number pattern>[<message id pattern>]]]=RC value

where <program pattern> is the external program that produced the output

shown in the job log and <message ID pattern> is the message class. For

example, the following line appended in the job log:

04/26/2005 10:08:04 00

550Step 001 started (program BTCTEST, variant GIULIO, user name TWSDEV)

will match the following pattern line in TWShome/methods/rcm/r3batch-joblog.rcm:

"*Step*" "*" "550" "*"=5

because:

<message text pattern>

"Step 001 started (program BTCTEST, variant GIULIO, user name

TWSDEV)"

<program pattern>

"*"

<message number pattern>

"550"

<message id pattern>

"*"

TWShome/methods/rcm/r3batch-pchainlog.rcm

Maps messages from the protocol of a Process Chain into return code values. If

this file is not present, the messages in the protocol are ignored.


<message number pattern>

[<message id pattern>[<message variable 1>[<message variable 2>

[<message variable 3>[<message variable 4>[<message type>]]]]]]=RC value

TWShome/methods/rcm/r3batch-spoollist.rcm

Maps messages in the job spool list of an R/3 job into return code values. If

this file is not present, the messages in the spool list are ignored.


<spool list row pattern>=RC value

TWShome/methods/rcm/r3batch-syslog.rcm

Maps messages in the syslog of an R/3 system into return code values. The

R/3 system log should be checked only when R/3 returns the generic 552 error

to r3batch.

If this file is not present, the messages in the system log are ignored.




|

|||

||

||

||

<system log row pattern>=RC value

If you plan to map system log messages, be sure to set the log_r3syslog option

of r3batch to ON (the default is OFF).

TWShome/methods/rcm/r3batch-msgrc.rcm

Maps ABAP exceptions and BAPI return codes of RFC function modules into

return code values. If this file is not present, the mapping is done using a

hardcoded table.


<message number>=RC value

<message number> is the error message number. The last message number is

always used. That is, if two error messages are generated, only the second one

is checked against the mapping file.

Mapping return codes for intercepted jobs

To set up return code mapping for intercepted jobs, after defining the appropriate

return code conditions in the r3batch-joblog.rcm file, do the following:

1. Create a customized template file named TWShome/methods/r3batch_icp/rctemplate.jdf containing the following:

alias;rccondsucc "Success Condition"

where the ″Success Condition″ must match a condition saved in the rcm file.

2. Modify the TWShome/methods/r3batch_icp/CPUNAME_r3batch.icp referring to the

jdf file you created as follows:

client job_mask user_mask rctemplate

Tivoli Workload Scheduler manages the intercepted R/3 job as a docommand

job with all the options specified in the customized jdf file. You can check if

your intercepted job is correctly submitted by reading the job_interceptor

joblog.



Mapping return codes for intercepted jobs


Chapter 29. Configuring the tracing utility

This chapter describes how to configure the trace utility for all the access methods.

Tivoli Workload Scheduler for Applications logs all the processing information in

the TWShome/methods/access_method.properties configuration file.

Note: If you delete this file accidentally, Tivoli Workload Scheduler for

Applications creates a new file with all the default values and contains the

following comment:

# This file was automatically created using the default values.

Customizing the .properties file

Depending on the access method you are working with, customize the trace

parameters in the following properties files:

mcmagent.properties

For the Oracle E-Business Suite access method.

psagent.properties

For the PeopleSoft access method.

r3batch.properties, r3evmon.properties

For the SAP R/3 access method.

With this access method, you can also specify debug and trace

parameters in the single job definitions. See “R/3 Job page” on

page 121 and “Task string to define SAP jobs” on page 129.

mvsjes.properties, or mvsca7.properties, or mvsopc.properties

For the z/OS access method, depending on the scheduler with

which you are working.

For each .properties file you can customize the following parameters:

access_method.trace.tracers.level

Specify the level of tracing you want to set. Possible values are:

DEBUG_MIN Only error messages are written in the trace file. This is the

default.

DEBUG_MID Informational messages and warnings are also written in the

trace file.

DEBUG_MAX

A most verbose debug output is written in the trace file.

The value you set in the .properties file applies to all the jobs of the

corresponding access method. To specify a different trace setting for a particular

job, specify the following option in the job definition:

-tracelvl=(1|2|3)

where:

v 1 = DEBUG_MIN

v 2 = DEBUG_MID

v 3 = DEBUG_MAX


||

|||

access_method.trace.handlers.traceFile.fileDir

Specifies the path where the trace file is created. Depending on the access

method, the default is:

SAP R/3

TWShome/methods/traces

All other access methods

TWShome/methods

Ensure that the new path you specify has already been created as a fully

qualified path with write permissions.

Traces are written in XML format. Always use slashes (or backslashes) when

you specify a new path, even if you are working on Windows operating

systems.

The trace files give information about the method execution to the desired level

of detail. The minimum trace level is always on, to guarantee a First-Failure

Data Capture (FFDC) ability. The trace file name is:

trace-mcmagent.log

For the Oracle E-Business Suite access method.

trace-psagent.log

For the PeopleSoft access method.

trace-r3batch.log, trace-xagent_name-r3evmon.log

For the SAP R/3 access method.

trace-mvsjes.log, or trace-mvsca7.log, or trace-mvsopc.log

For the z/OS access method. Depending on the scheduler with which you

are working.

access_method.trace.tracers.logging

Specifies to enable or disable the trace utility. Possible values are:

true To enable the trace utility. This is the default value.

false To disable the trace utility. If you set this parameter to false, no traces

are written in the trace-access_method.log file even if there are problems.

r3batch.trace.handlers.traceFile.maxFiles

The maximum number of trace files that are created before the oldest one is

deleted. If this parameter is set to 1, the current trace file is never replaced and

can grow without limit.

r3batch.trace.handlers.traceFile.maxFileSize

The maximum size (in bytes) that the trace file can reach before it is renamed

and a new trace file is created. This parameter is valid only if the

r3batch.trace.handlers.traceFile.maxFiles is set to a value greater than 1.

Configuring the .properties file


||

||

1111

1111

Configuration file example for the SAP access method

The following r3batch.properties file is an example of a configuration file for the

SAP access method with the following characteristics:

v The level of tracing set is DEBUG_MID. This means that not only error messages

but also informational messages and warnings are written in the trace file.

v The trace file is created in the home/maestro/methods directory.

v The tracing process creates three trace files, whose maximum size can be 10 MB.r3batch.organization=IBM

r3batch.product=TWS4APPS

r3batch.component=R3BATCH

r3batch.trace.tracers.level=DEBUG_MID

r3batch.trace.tracers.listenerNames=r3batch.trace.handlers.traceFile

r3batch.trace.tracers.logging=true

r3batch.trace.handlers.traceFile.fileDir=home/maestro/methods

r3batch.trace.handlers.traceFile.formatterName=r3batch.trace.formatter

r3batch.trace.handlers.traceFile.maxFileSize=104805100

r3batch.trace.handlers.traceFile.maxFiles=3

Configuration file example for the SAP R/3 access method

Chapter 29. Configuring the tracing utility 249

1

Configuration file example for the SAP R/3 access method


Chapter 30. Troubleshooting

This chapter describes a number of problems that might occur when installing or

using Tivoli Workload Scheduler for Applications or the access methods.

Known installation problems

Table 68 lists known installation problems.

Table 68. Known installation problems

Area Item

ISMP installation

on Solaris version

5.8 and 5.9

Symptom: On Solaris version 5.8 and 5.9, the installation of Tivoli Workload Scheduler for

Applications with InstallShield (both interactive and silent), randomly displays the following

error message:

error calculating the uncompressed size of bundled JRE or it is corrupted

Cause and Solution: This is due to a performance problem. To solve the problem, set the value

of the OPTED_SPB_BEAN.estimatedTimeToInstall parameter to 1000.

ISMP installation

on HP-UX version

11i v1

Symptom: On HP-UX version 11i v1, the installation of Tivoli Workload Scheduler for

Applications with the InstallShield wizard randomly displays the following error message, even

if the installation was successfully performed:

Install Shield got an error while updating VPD catalog... or updating key...

Cause and Solution: This is due to an InstallShield error. The Tivoli Workload Scheduler for

Applications installation completes successfully. You can ignore the message.

ISMP installation

on HP-UX version

11.0

Symptom: Installation of Tivoli Workload Scheduler for Applications with InstallShield (both

interactive and silent) fails on specific HP-UX operating systems (HP-UX version 11.0) with the

following message:

Bundled JRE is not binary compatible with host OS/Arch or it is corrupt.

Testing bundled JRE failed.

Cause and Solution: This is due to the value set for the maxdsiz kernel parameter.

Set the value to 0x06000000 hex (100663296).


Table 68. Known installation problems (continued)

Area Item

Installing the

language pack

Symptom: When installing the Tivoli Workload Scheduler for Applications language pack, it

remains in pending state or the following message is displayed:

A suitable JVM could not be found.

Please run the program again using the option -is:javahome JAVAHOME_DIR

Cause and Solution: The problem occurs because the installation program cannot find the Java

Virtual Machine (JVM) in the /methods/_tools path directory and is looking for it in all the

directories. Wait a few minutes and if the installation program does not continue or the above

message is displayed, perform the following steps:

1. Stop the installation program if it remains in pending state or click OK if the message is

displayed. The installation program exits.

2. Set the JAVAHOME_DIR to twsinstallationdir/methods/_tools using the following

command:

is:javahome twsinstallationdir/methods/_tools

or set the TWS4APPS_JDKHOME environment variable to the following path:


In a UNIX environment

This variable is located in /etc/profile file.

In a Windows environment

This variable is located in the HKEYLOCAL_MACHINE->SYSTEM->ControlSet001->Control->SessionManager->Environment->TWS4APPS_JDKHOME registry key.

Installing the

language pack

Symptom: If you cancel the installation of a Tivoli Workload Scheduler for Applications

language pack, a Java exception is displayed:

ServiceException: (error code = 315; message = "product bean

R3BATCH_SOLARIS64_C OMPONENT_BEAN does not exist"; severity = 0)

Cause and Solution: The Tivoli Workload Scheduler for Applications language pack is installed.

To uninstall it, proceed as described in “Uninstalling” on page 36.




Area Item

Uninstalling the

product

Symptom: You are unable to uninstall Tivoli Workload Scheduler for Applications or its

language pack. The following directories are present:

To uninstall Tivoli Workload Scheduler for Applications

./_xauninst /, ...,_xauninstn

To uninstall the language pack

./_lxauninst:,/, ...,_lxauninstn

Cause and Solution: Possible causes are:

v You launched the uninstaller command from the _xauninst or _lxauninst directories, and

you did not exit from those directories to complete the uninstallation.

v You did not remove the _xauninst or _lxauninst directories after the uninstallation

completed successfully.

To solve the problem, run the following command:

On all the operating systems, except HP-UX and Solaris

twsinstallationdir/methods/_tools/_jvm/jre/bin/

java -jar twsinstallationdir/methods/_xauninstn/uninstall.jar

or

twsinstallationdir/methods/_tools/_jvm/jre/bin/

java -jar twsinstallationdir/methods/_lxauninstn/uninstall.jar

On HP-UX and Solaris

twsinstallationdir/methods/_tools/_jvm/bin/

java -jar twsinstallationdir/methods/_xauninstn/uninstall.jar

or

twsinstallationdir/methods/_tools/_jvm/bin/

Java -jar twsinstallationdir/methods/_lxauninstn/uninstall.jar

where:

twsinstallationdir

The directory where you installed the product.

n The number of directories that have been created. For example, _xauninst1, _xauninst2.


Chapter 30. Troubleshooting 253


Area Item

Uninstalling the

product

Symptom: Uninstalling the base product or its language pack uninstalls also the Java Virtual

Machine (JVM), therefore you are unable to:

v Uninstall another product package

v Use the Option Editor

v Submit PeopleSoft jobs

Cause and Solution: To install JVM again, perform the following steps:

1. According to your operating system, run the following command from TWShome/INSTALLER:

For Windows

setup.exe -is:extract

For the other operating systems

setup.bin -is:extract

The JVM file installer is extracted to the TWShome/INSTALLER directory.

2. Create the directory inst/methods/_tools.

3. From TWShome/INSTALLER copy the following executable file to the inst/methods/_tools

directory:

AIX ibm142_swd_aix.bin

HP-UX for PA-RISC ibm-jre-n142p-hpux10-installer.bin

HP-UX for Integrity ibm142_swd_hpia64.bin

Linux ibm142_swd_linux.bin

Sun Solaris Operating Environment

ibm142_swd_solaris.bin

Sun Solaris Operating Environment for Opteron

ibm142_swd_solaris2-ix86.bin

Windows ibm142_swd_win32.bin

4. To install JVM again, from inst/methods/_tools run the executable file.



1111111

1

1

11

11

1

1

11

11

11

11

11

11

11

11

1


Area Item

Uninstalling with

twsappsint

Symptom: You are unable to upgrade to Tivoli Workload Scheduler for Applications version 8.4,

try to uninstall the product, but the uninstallation process leaves some packages in the catalog.

Cause and Solution: List the packages that were not removed by running the following

commands:

cd product_image/opsys/ALT_INST/_swdcli

. ./swd_env.sh

wdlssp

Where:

product_image The Tivoli Workload Scheduler for Applications image file.

opsys The operating system to which the image file applies.

The product packages that were not removed are shown as follows:

...

------------------------------------------------------

DISSE0164I Name : TWS4APPS_instance_package

DISSE0164I Version : version

DISSE0164I State : state

------------------------------------------------------

...

Where:

instance The instance name.

package The package name.

version The package version.

state The package state.

From the same shell, uninstall the product packages manually by running the following

command:

wdrmvsp -f TWS4APPS_instance_package.version



||||

||

|||

|||||

|

|||||||

|||||||||

||

|


Area Item

Uninstallation

with ISMP

Symptom: You are unable to uninstall the extended agent with ISMP, because monitoring

processes were running.

Cause and Solution: List the package that was not removed by running the following

commands:

cd product_image/opsys/ALT_INST/_swdcli

. ./swd_env.sh

wdlssp

Where:

product_image The Tivoli Workload Scheduler for Applications image file.

opsys The operating system to which the image file applies.

The product package that was not removed is shown as follows:

...

------------------------------------------------------

DISSE0164I Name : TWS4APPS_instance_package

DISSE0164I Version : version

DISSE0164I State : state

------------------------------------------------------

...

Where:

instance The instance name.

package The package name.

version The package version.

state The package state.

From the same shell, uninstall the product package manually by running the following

command (before uninstalling, ensure that you stopped all monitoring processes):

wdrmvsp -f TWS4APPS_instance_package.version



||||

||

|||

|||||

|

|||||||

|||||||||

||

|

Other known problems

Table 69 lists miscellaneous troubleshooting problems.

Table 69. Miscellaneous troubleshooting items

Area Item

r3batch:

monitoring SAP

events is not

performed

Symptom: The SAP events on which the event rule is based are not monitored nor committed.

Solution: The SAP events being monitored are listed in the following file:

twshome/monconf/XAname_r3evmon.cfg

where XAname is the name of the SAP extended agent workstation.

Check that the file is updated and contains the current monitoring plan. The SAP events are

indicated by the following keyword (one for each SAP event on the same extended agent):

!R3EVENT SAP_event_name_lengthSAP_event_name[SAP_event_parm_lengthSAP_event_parm]

where:

SAP_event_name_length

The length of the SAP event name to monitor, in the format nnnn. For example, 0008, if the

event name is SAP_TEST.

SAP_event_name

The name of the SAP event to monitor.

SAP_event_parm_length

The length of the parameter associated with the SAP event to monitor, if any. The format is

nnnn. For example, 0007, if the event name is SAP_PAR.

SAP_event_parm

The parameter associated with the SAP event to monitor, if any. This value is optional, but

omitting it identifies an SAP event with no parameter associated. For details about how the

events are matched between r3evmon.cfg and the SAP system, see “SAP events matching

criteria” on page 191.

For each configuration file, an r3evmon process is started to monitor the SAP events listed. To

start an r3evmon monitoring process for a specific extended agent workstation, enter the

following command.

Notes:

1. For UNIX only, r3evmon must be entered by the owner of the Tivoli Workload Scheduler

installation:

2. If you run r3evmon from a Windows DOS shell, the command prompt is not returned until

the process completes.

r3evmon -t SEM -c XAname -- "[-EIFSRV EIF_server -EIFPORT EIF_port]"

where:

XAname The name of the extended agent workstation.

EIF_server The host name or IP address of the master domain manager.

EIF_port The port that the master domain manager uses to receive the event

notification.

r3batch:

monitoring SAP

events is not

performed

Symptom: The SAP event on which the event rule is based is neither monitored nor

committed.

Solution: Ensure that the extended agent workstation you specified in the SAP event

definition exists. When you define an SAP event within an event rule, no check on the

extended agent workstation is made: if the workstation does not exist, the event rule is saved

and activated but it will never be resolved.



||||

|

|

|

|

||

|

|

|||

||

|||

|||||

|||

|

||

||

|

|

||

||

|||

||||

||

||||

Table 69. Miscellaneous troubleshooting items (continued)

Area Item

r3batch:

monitoring SAP

events is not

performed

Symptom: With XBP 3.0, the SAP event is raised but Tivoli Workload Scheduler is not notified

and therefore does not act as expected.

Solution: Ensure that the SAP event was not excluded from logging in the SAP event history

table.

r3batch:IDoc

monitoring is not

performed

Symptom: The events on which the event rule is based are not monitored or no event is

generated during IDoc monitoring.

Solution: The events being monitored are listed in the following file:

twshome/monconf/XAname_r3evmon.cfg

where XAname is the name of the SAP extended agent workstation. It is the same file used to

monitor SAP events in general.

Check that the file is updated and contains the current monitoring plan. The events

corresponding to the IDOCEventGenerated event type are indicated by the following keyword

(one for each event on the same extended agent):

!IDOC nnnn<Client Number>nnnn<IDoc Status List>nnnn<Direction>nnnn<Receiver Port>

nnnn<Receiver Partner Type>nnnn<Partner Function of Receiver>

nnnn<Partner Number of Receiver>nnnn<Sender Port>nnnn<Sender Partner Type>

nnnn<Partner Function of Sender>nnnn<Partner Number of Sender>

nnnn<Message Type>nnnn<IDoc Type>nnnn<Logical Message Variant>

nnnn<Logical Message Function>nnnn<Test Flag>nnnn<Output Mode>

where:

nnnn

The length of the IDoc field. For example, 0005 indicates the value of an IDoc status list

corresponding to 56,60.

< >

Contains the value of the field associated with the IDoc to be monitored. For a list of the

supported IDoc fields, refer to Table 49 on page 196.

For each configuration file, an r3evmon process is started to monitor the events listed. Make

sure that an r3evmon monitoring process is started for the involved extended agent

workstation.

r3evmon:

monitoring SAP

and IDoc events

increases memory

consumption

Symptom: Memory consumption increases continuously during monitoring of IDoc and

standard SAP events.

Solution: Refer to SAP Notes 1021071 and 1109413.



||||

||

||

111

11

11111

11

1


Area Item

r3batch:

Duplicated events

generated during

IDoc monitoring

Symptom: The action defined in an event rule with IDOCEventGenerated event type is

unexpectedly repeated.

Solution: Reset the start date and time for the next monitoring loop. These values are stored in

the following file:

twshome/monconf/XAname_r3idocmon.cfg

where XAname is the name of the SAP extended agent workstation. Therefore you can either:

v Stop r3evmon, delete the XAname_r3idocmon.cfg file and then start r3evmon again.

- OR -

v Stop r3evmon, set the date and time in the XAname_r3idocmon.cfg file to the values you

want, and startr3evmon again.

Use the following format for the start date and time:

start_date=YYYYMMDD

start_time=HHMMSS

For example:

start_date=20080307

start_time=115749

Check the value of the idoc_no_history option:

v If it is set to OFF and no XAname_r3idocmon.cfg file exists, then all matching IDocs are

retrieved, not only the current ones.

v If it is set to ON (default value), check the date and time in the XAname_r3idocmon.cfg file.

r3batch: No event

is generated during

IDoc monitoring

Symptom: The expected event actions are not triggered.

Solution: Check the value of the idoc_no_history option; if it is set to ON (default value),

check the date and time in the XAname_r3idocmon.cfg file.

r3batch: error

message when

scheduling SAP

jobs

Symptom: When creating an SAP job, the following message is displayed while trying to view

the details of an ABAP’s variant:

AWSO0101E

Missing ABAP routine.

J_101_REPORT_ALL_SELECTIONS please install the latest ABAP routine for Maestro!!

Solution: This defect is caused by an error in an SAP function module. SAP describes this

problem and possible solutions in the SAP notes 0351293 and 0116354.

r3batch: modify

job step error

You change print parameters with the BAPI_XBP_MODIFY_JOB_STEP function module, and

subsequently, they are incorrect. As a consequence, r3batch gets error 221:

MSG_CANNOT_GET_PRIARC_PARAMS: "Retrieving new print and archive parameters failed"

The problem is solved by installing SAP note 758829.

r3batch: modify

job step error

The BAPI_XBP_MODIFY_JOB_STEP function module always uses the name of the logged-on

user as the name for the step user. In this case, when submitting a job with the -vX options,

r3batch creates a job by copying all the data from the original template, except the variant

name of the first step (which is provided as the option parameter). This procedure is usually

referred to as the ″old copy″. However, when adding a step to a new job, the XBP 2.0 interface

ignores the user parameter passed by r3batch.

The problem is solved by installing SAP note 758829.



1111

11

111

1


Area Item

When you restart

the process of a

subchain, the status

of the original

process chain is not

changed to active

Symptom: When you restart the process of a subchain, the status of the original process chain

is not changed to active.

Solution: Refer to SAP Note 1075876.

psagent: misleading

message displayed

if the local options

file has no right

permissions

The job log shows the following message:

EEW00439E You did not specify the required options either in the global

or in the local options file.

but all the mandatory options were correctly set in the options file.

Check that the options file has read and write permissions available to the user who is trying

to launch the job.

No messages

written in the job

log

Symptom: Tivoli Workload Scheduler for Applications does not write any messages in the job

log if the file system for tracing is full or the ljuser does not have the correct permission to

write in the trace directory.

The submission of

a PeopleSoft job

fails

Symptom: The submission of a PeopleSoft job fails and the Tivoli Workload Scheduler job log

contains a Java exception similar to the following:

Exception in thread "3194" java.lang.ExceptionInInitializerError

at bea.jolt.JoltSessionAttributes.<clinit>(JoltSessionAttributes.java:183)

at psft.pt8.net.JoltSessionPool.createConnection(JoltSessionPool.java:363)

at psft.pt8.net.JoltSessionPool.getJoltSession(JoltSessionPool.java:220)

Cause and Solution: The psjoa.jar path contains special characters.

Define a path without special characters.

The submission of

an Oracle job fails

Symptom: The submission of an Oracle job fails and the Tivoli Workload Scheduler job log

shows the following information:

EEWP0017 Child MCMLJ exited normally.

Exit code: 1.EEWP0027 Error - Launch job failed

Solution: Submitting an Oracle job might fail because there is a connection problem to the

Oracle database. Verify that your Oracle naming methods are set correctly. For details about

how to configure naming methods, refer to the Oracle Net Services Administrator's Guide.

mvsjes: RACF

authorization

problem on z/OS

version 1.7

Symptom: An S047 abend is returned if the EEWSERVE started task does not have an associated

RACF owner ID.

Solution: In the RACF database, associate an authorized RACF ID with the EEWSERVE started

task as specified in “Setting RACF authorizations on z/OS” on page 211.



111111

11

||||

||

|||


Area Item

Error defining an

internetwork

dependency based

on SAP event

Symptom: If you work with XBP 2.0, when you try to define an internetwork dependency

based on an SAP event the following error message is displayed:

*** ERROR 778 *** EEWO0778E An internal error has occurred. The program could not

modify the following job:

Job name:

Job ID:

%CJ ERROR

Solution: Perform the following steps:

1. Check if the BCTEST report is defined in your SAP system by invoking either one of the

following transactions:

SA38 Enter BTC* and click the picklist button. In the panel that opens, click the picklist

button and check if BTCTEST is shown in the list that is displayed.

SE38 Enter BTC* and click the picklist button. Check if BTCTEST is shown in the list

that is displayed.

2. If report BTCTEST is not found in the list, you can either:

v Choose another existing report, and, in the local options file, set the

placeholder_abap_step option to the name you chose. Because the report assigned to the

placeholder job is run when the corresponding event is raised, ensure that you choose a

dummy report. For details about the placeholder_abap_step option, see Table 33 on page

106.

- OR -

v Set the placeholder_abap_step option to a custom developed ABAP code of your choice.

Troubleshooting the SAP R/3 connection

If you are unable to submit SAP R/3 jobs using Tivoli Workload Scheduler after

the R/3 configuration, perform the following tests:

v Ensure you can ping the SAP R/3 system from the Tivoli Workload Scheduler

system. This shows basic network connectivity.

v Note that using the SAP R/3 routers to access the R/3 system could exceed the

size of internal buffers of the RFC library used to store the hostname of the SAP

R/3 system. When this occurs, the hostname gets truncated, causing the

connection to the R/3 system to fail. To work around this problem, do not fully

qualify the name of the SAP R/3 routers or alternatively use the IP addresses.

v Run the following telnet command to verify connectivity:

telnet systemname 33xx

where systemname is the system name or IP address of the SAP R/3 server and

xx is the SAP R/3 instance.

If the command fails to complete, this means that communication between

r3batch and the SAP R/3 application server is down.

v Log on to the SAP R/3 system as an administrator and verify that the Tivoli

Workload Scheduler RFC user (created in the “Creating the IBM Tivoli Workload

Scheduler RFC user” on page 95) exists.

v If the SAP R/3 gateway truncates the connection string, replace the host name

with the IP address.

v If r3batch runs on an AIX system that does not use U.S. English, make sure that

the U.S. Language Environment is installed on both the IBM Tivoli Workload



Scheduler workstation and the SAP R/3 database workstation. Otherwise the

error BAD TEXTENV (or a similar error message) might appear in the dev_rfc trace

file and connections to SAP R/3 fail.

Troubleshooting the SAP R/3 connection


Chapter 31. Messages

This chapter describes many of the messages issued by Tivoli Workload Scheduler

for Applications and its agent processes.

It is divided into the following sections:

v “IBM Tivoli message format” explains the message standard used by Tivoli

Workload Scheduler for Applications.

v The messages, presented in alphabetic order of the subcomponent codes. The

following table helps you to find message help for a specific component.

Table 70. Tivoli Workload Scheduler for Applications messages - component codes

Message set description Message component ID Page number of

message help

twsappsinst installation EEW AI 266

z/OS gateway EEW I 270

PeopleSoft access method EEW N 276

R/3 access method EEW O 278

Oracle access method EEW P 313


Visualized Data Centers, used

by the PeopleSoft access method

HTWGT 314

Note: This guide does not contain any details about Informational messages,

because they are complete within themselves, and do not need further

explanation.

IBM Tivoli message format

This section describes the format of the message that is displayed on your screen

or written in a log file. A message consists of a message number and a message

text. This chapter also includes help for many of the more important error and

warning messages. This help consists of an explanation of the message, a

description of what the system does, and information about what you should do to

solve the problem.

These items are described in more detail in the following sections.

Message number

Tivoli Workload Scheduler for Applications message numbers (codes) have the

following format:

<xxx><component_code><numeric_identifier><severity>

where the parts of the message are as follows:

<xxx>

The product prefix, which can be:

EEW For all Tivoli Workload Scheduler for Applications messages.


||

||

HTWGT

For Tivoli Workload Scheduler for Visualized Data Centers, used by the

PeopleSoft access method messages.

<component_code>

An alphabetic code for the Tivoli Workload Scheduler for Applications

component, as follows:

AI Tivoli Workload Scheduler for Applications twsappsinst installation

messages.

I Tivoli Workload Scheduler for Applications z/OS gateway messages.

O Tivoli Workload Scheduler for Applications R/3 access method

messages.

P Tivoli Workload Scheduler for Applications Oracle access method

messages.

N Tivoli Workload Scheduler for Applications PeopleSoft access method

messages.

<numeric_identifier>

A 2-, 3-, or 4-digit numeric identifier that is unique within any combination of

prefix and component code.

<severity>

The severity indicator, as follows:

I Informational: Informational messages provide users with information

or feedback about normal events that have occurred or are occurring, or

request information from users in cases where the outcome will not be

negative, regardless of the response.

Examples:

v The status request is processing.

v The files were successfully transferred.

v Do you want to save your output in file a or in file b?

W Warning: Warning messages indicate that potentially undesirable

conditions have occurred or could occur, but the program can continue.

Warning messages often ask users to make decisions before processing

continues.

Examples:

v The replay table could not be sent. The link to Agent_name proceeds

with a reduced replay protocol.

v A file already exists with the same name. Do you want to overwrite

this file?

E Error: Error messages indicate problems that require intervention or

correction before the program can continue.

Examples:

v The specified file could not be found.

v You are out of space on the x drive. The file cannot be saved to this

drive.

An example of an error message number is as follows:

EEWAI004E

Message format


|||

Message text

Every attempt has been made to represent the message text exactly as it appears to

the user in the displayed or written message. Any differences that occur are

usually caused by the different layout of the book (in two columns) with respect to

the message display panel or log.

Where the system has included variable information in the message text, this

variable information is represented in this guide by an italicized label, describing

the type of information referred to by the variable. For example, if the message text

that appears on your screen is:

The replay table could not be sent.

The link to TRC8470 will proceed with a reduced replay protocol.

the message text shown in the guide would be:

The replay table could not be sent.

The link to agent_name will proceed with a reduced replay protocol.

In this case the label agent_name tells you that the information that will be inserted

by the system is the name of the agent which could not receive the replay table.

Message help

This chapter provides you with help for many of the more important error and

warning messages. This help provides the following:

Explanation

An explanation, where necessary, of the message text.

System action

A description of what the system or process does as a result of the condition

that caused the message.

Operator response

What you should do in response to the condition that caused the message.

Often you will be able to resolve such conditions yourself, but sometimes you

will be asked to contact IBM Software Support.

See also

A reference to any Tivoli Workload Scheduler for Applications documentation

that might give you assistance with understanding or resolving the problem.

Message format

Chapter 31. Messages 265

twsappsinst installation messages - AI

This section lists error and warning messages that might be issued by the Tivoli

Workload Scheduler for Applications twsappsinst installation method.

EEWAI002E The installation program cannot convert

the Software Distribution catalog

correctly. For detailed information, refer

to the log file: log_file_name.

Explanation: See message.

System action: The installation program stops. The

installation is not completed.

Operator response: Analyze the log file, correct the

error, and resubmit the installation.

EEWAI003E The "twsappsinst" installation program

cannot uninstall Tivoli Workload

Scheduler for Applications. For detailed

information, refer to the log file:

log_file_name.


System action: The "twsappsinst" installation program

stops. The uninstallation is not performed.


error, and resubmit the uninstallation. Possible causes

of the error can be the following:

v One or more of the files needed to perform the

uninstallation are missing. Ensure that if you have

copied the installation program and its associated

files from the product CD, that all required files have

been copied. You are recommended that if you do

not want to run the uninstallation directly from the

CD, that you copy the entire CD to hard disk, to

ensure to maintain the correct relationship between

the files used by the installation program when

performing the uninstallation.

v You do not have the root permissions necessary to

perform the operation. In this case, either give

yourself the required permissions, or run the

installation as a user that has the required

permissions.

EEWAI004E The installation program cannot install


Applications. For detailed information,

refer to the log file: log_file_name



operation is not performed.


error, and resubmit the installation. Possible causes can

be:

v One or more of the files needed to perform the

installation are missing. Ensure that if you have

copied the installation program and its associated

files from the product CD, that all required files have

been copied. You are recommended that if you do

not want to run the installation directly from the CD,

that you copy the entire CD to hard disk, to ensure

to maintain the correct relationship between the files

used by the installation program when performing

the installation.

v You do not have the root permissions necessary to

perform the operation. In this case, either give

yourself the required permissions, or run the

installation as a user that has the required

permissions.

EEWAI006E There is a syntax error in the

installation option specification. The

correct syntax is as follows:

"option_name".




Operator response: Correct the syntax and resubmit

the command. To verify the syntax use the following

command: twsappsinst -u.

See also: The User’s Guide for details of the command

syntax.



following option is specified more than

once: "option_name"




Operator response: Correct the syntax and resubmit

the command. To verify the syntax use the following



syntax.

EEWAI008W The supplied language ID: "

language_ID" is not valid. The language

of the installation program will default

to English.

Explanation: See message. Note, this refers to the

language of the installation program, not the language

of the installed product.

EEWAI002E • EEWAI008W


System action: The process continues.

Operator response: None.

EEWAI009E The "twsappsinst" installation program

does not work on the

operating_system_name operating system

running on this computer.




Operator response: Verify the supported operating

systems and choose a different operating system on

which to install Tivoli Workload Scheduler for

Applications.

See also: The User’s Guide or Release Notes for the list

of supported operating systems.

EEWAI010E You must have root permissions to run

the "twsappsinst" installation program.




Operator response: Either add root permissions to the

user you were logged on as and resubmit the

installation, or logon as a user with root permissions

and resubmit the installation.


installation option specification. You

must specify at least one option to run

the "twsappsinst" installation program.




Operator response: Resubmit the command specifying

at least one of the required options. To verify the

syntax run the following command: twsappsinst -u.


syntax.



first option specified must be one of the

following: "-install", "-upgrade",

"-languages", "-uninst".




Operator response: Resubmit the command,

specifying one of the options listed above as the first

option. To verify the syntax run the following



syntax.



following option is specified more than

once: "option_name".




Operator response: Resubmit the command, ensuring

that the installation option is supplied only once. To

verify the syntax run the following command:

twsappsinst -u.


syntax.



"option_name" option is not allowed

when the "option_name" option is

specified.





to supply the correct combination of options. To verify

the syntax run the following command: twsappsinst -u.


syntax.



option_name option can only be specified

when the option_name option is

specified.





to supply the correct combination of options. To verify

the syntax run the following command: twsappsinst -u.


syntax.

EEWAI009E • EEWAI017E




option_name option cannot be specified

for the operating_system operating

system.




Operator response: Verify in the User’s Guide which

options are available for the operating system where

you are installing the product. Either choose to install

the product on a different operating system, or install

the product on the original operating system but using

only the permitted options.


syntax.


installation option specification. An

unrecognizable option has been

specified: "option_name".





that the options you require are specified correctly. To


twsappsinst -u.


syntax.


installation option specification. A

required option was not specified:

"option_name".





that all the required options are specified correctly. To


twsappsinst -u.


syntax.


installation option specification. At least

one "LJuser" must be specified with the

"-install" option.





that at least one "LJuser" is specified. To verify the

syntax run the following command: twsappsinst -u.


syntax.

EEWAI022E The TWSuser that was specified:

"user_name" is not the TWSuser of any

Tivoli Workload Scheduler installation.




Operator response: Do one of the following:

v Resubmit the command, specifying a different

TWSuser that is the valid TWSuser of a Tivoli

Workload Scheduler installation.

Install Tivoli Workload Scheduler using this TWSuser,

and then resubmit this command as before.

EEWAI023E The installation program cannot locate

the home directory of the specified

TWSuser: "user_name".




Operator response: Verify that the TWSuser you

specified has an associated home directory and ensure

that it contains Tivoli Workload Scheduler. If Tivoli

Workload Scheduler is installed in a directory other

than the home directory of the TWSuser, resubmit the

installation command, supplying the following option

to identify the installation directory of Tivoli Workload

Scheduler: -inst_dir <TWS_installation_directory>.

EEWAI025E The supplied Tivoli Workload Scheduler

directory path contains blank characters,

which are not permitted.




Operator response: If Tivoli Workload Scheduler is

installed in a path that includes spaces, change that

path so that there are no spaces in it, and resubmit the

command. Otherwise, you have supplied an incorrect

path, and should resubmit the command without any

spaces in the installation directory path.


syntax.



EEWAI026E The supplied Tivoli Workload Scheduler

directory does not exist:

"TWS_installation_directory".




Operator response: Resubmit the command,

supplying the correct name of the Tivoli Workload

Scheduler directory.

EEWAI027E The installation program failed for an

unspecified reason. For details, see the

log file: "log_file_name".




Operator response: Analyze the log file, looking at the

messages that preceded this one. Correct the error and

resubmit the installation program.


installation option specification. Using

the "-install" option, the "-psjoapath"

option can be specified only if

"-ps_ljuser" is also specified.





that "ps_ljuser" is also specified. To verify the syntax

run the following command: twsappsinst -u.


syntax.

EEWAI036E The value of the "-psjoapath" option

does not point to a valid psjoa.jar file.





that the full path to an existing psjoa.jar file is specified

as the "-psjoapath" option value.


syntax.



z/OS gateway messages - I

This section lists error and warning messages issued by the z/OS gateway

processes. Most messages contains a reference to modules. Table 71 includes a list

of these modules.

Table 71. z/OS module names

Module Name Description

EEWPRE84 Previous SMF exit

EEWTCP00 Main processing routine

EEWTCP01 Server test vehicle

EEWTCP02 Main dataspace construction routine

EEWTCP05 Establish ESTAE routine to issue failure message

EEWTCP07 Find data set name associated with open ACB/DCB

EEWTCP08 Find data set name associated with DDNAME

EEWTCP10 Initialize and examine variables

EEWTCP15 Locate and initialize control blocks

EEWTCP20 Locate and initialize control blocks

EEWTCP21 Client test vehicle



EEWTCP25 Concurrent server

EEWTCP26 Concurrent server Interlink TCP/IP provider

EEWTCP27 Concurrent server for Openconnect TCP/IP stack

EEWTCP30 Child server task

EEWTCP31 Child server task for Interlink TCP/IP stack

EEWTCP32 Child server task

EEWTCP84 SMF record exit for SMFEWTM

EEWTCP87 IBM Tivoli Workload Scheduler interface

EEWTCP88 IBM Tivoli Workload Scheduler interface post

EEWTCP89 CA-7 BTI

EEWTCP90 Issue command and wait for response

EEWTCP91 Issues TERROR to format messages and issues WTOS

EEWTCP92 Find substring within string

EEWTCP93 Issue CA-7 command and wait for response

EEWTCP94 STIMER exit to post ECB past in parm

EEWTCP95 Calls IKJEFF02 to extract buffer using EEWTCP99

EEWTCP96 ESTAE routine to issue failure message

EEWTCP97 Calls IKJEFF19 (DAIRFAIL/VSAMFAIL) to issue message

EEWTCP98 Calls IKJEFF02 to issue message from EEWTCP99

EEWTCP99 Message table

EEWTCPC7 Check CA-7 job

EEWTCPCA Check application request handler


Table 71. z/OS module names (continued)

Module Name Description

EEWTCPCF Check file request handler

EEWTCPCJ Check job request handler

EEWTCPCO Check operation request handler

EEWTCPCV Enumerate job

EEWTCPED String encrypt/decrypt

EEWTCPEJ Enumerate job request handler

EEWTCPFJ Free job request handler

EEWTCPIA Insert application

EEWTCPIE String initialization

EEWTCPKJ Kill job request handler

EEWTCPKO Delete IBM Tivoli Workload Scheduler application

EEWTCPL7 Launch CA-7 job request handler

EEWTCPLJ Launch job request handler

EEWTCPLO Insert IBM Tivoli Workload Scheduler application

EEWTCPQ7 Query CA-7 job request handler

EEWTCPQJ Query job request handler

EEWTCPQO Query IBM Tivoli Workload Scheduler application

EEWTCPQS Query subsystem request handler

EEWTCPRC Return code

EEWTCPSC System abend

EEWTCPSE String encryption/decryption

EEWTCPUC User abend

EEWTCPWT Wait for specified amount of time

EEWTCPXX Invalid request handler

All the messages listed below are written in the EEWSPACE or in the EEWSERVE

log files. These are the files indicated in the SYSTSPRT DD card of the respective

procedure. In the files the messages are written starting from column 1, except for

the messages that do not contain the date and time after the message identifier, for

example EEWI27I. These messages appear with different characteristics in the

z/OS system and on the Tivoli Workload Scheduler. In the z/OS system log the

messages appear in the text of another message and in some cases they might

appear truncated. This is because the maximum length of each text record is 251

characters. In Tivoli Workload Scheduler they are always displayed in their

complete form.

EEWI01E yymmdd hhmmss module FAILED,

MACRO macro NEAR LABEL label

WITH RETURN CODE = reason code &

REASON CODE = reason code

Explanation: The specified module failed because an

error occurred in the specified macro. One possible

cause might be a TCP/IP connection problem.

yymmdd hhmmss The date and time the error occurred.

module The name of the module that issued

the message. For a detailed list, see


macro The name of the macro after that the

error message was issued.

label The name of the label in the source

code nearest to the instruction that

failed.

EEWI01E


return code The return code value.

reason code The reason code value.

System action: The system proceeds.

Operator response: Verify the return code and the

reason code specified in the message to understand the

error. If the problem persists contact IBM Software

Support for assistance.

EEWI02E yymmdd hhmmss module FAILED,

MACRO macro NEAR LABEL label

WITH RETURN CODE = return code &

ERROR NUMBER = error number

Explanation: The specified module failed because an

error occurred in the specified macro. One of the

possible causes can be TCP/IP connection problem.





macro The name of the macro after which

the error message is issued.



failed.

return code The return code value.

error number The error number.


Operator response: Verify the return code and the

error number specified in the message to understand

the error. If the problem persists contact IBM Software


EEWI08S yymmdd hhmmss module FAILED, AT

OFFSET offset

Explanation: See text. This message is issued by the

ESTAE routine.





offset The offset value.

System action: The system stops.

Operator response: Set SVCDUMP to YES collect the

dump and send it to IBM Software Support for

assistance.

EEWI10S yymmdd hhmmss module ABENDED

WITH ASSOCIATED REASON CODE

reason code

Explanation: The specified module ended abnormally

with the specified reason code.





reason code The reason code value.


Operator response: Restart the start task that contains

the module. If the problem persists contact IBM

Software Support for assistance.

EEWI15E yymmdd hhmmss module DATASET

″dataset″ DDNAME ″dd″ FAILED TO

OPEN NEAR LABEL label

Explanation: The specified data set is not available.






data set The name of the data set that failed to

open.

dd The internal dd.



failed.

Operator response: Verify one of the following

conditions:

v The data set was not deleted.

v The data set is not in use.

v You are authorized to use the specified data set.

If the problem persists contact IBM Software Support

for assistance.

EEWI18E yymmdd hhmmss module INVALID

TERMINATOR term

Explanation: You specified an invalid value for the

TERMINATOR parameter.





term The value you assigned to the



EEWI02E • EEWI18E


Operator response: Specify a valid value for the

TERMINATOR parameter and restart the start task. The

default value is x’25’.

EEWI19E yymmdd hhmmss module near label label

invalid value found name = value

Explanation: You specified an invalid value for the








failed.

name The name of the variable that has an

invalid value.

value The actual value of the variable.


Operator response: Specify a valid value for the

TERMINATOR parameter and restart the module. The

default value is x’25’.

EEWI20E yymmdd hhmmss module NEAR LABEL

label FAILED TO FIND ACTIVE SMF

IEFU84 EXIT

Explanation: The IEFU84 exit is not active.







failed.


Operator response: Activate the IEFU84 exit.

EEWI24E yymmdd hhmmss module NEAR LABEL

label error description

Explanation: The IEFU84 exit is not active.







failed.

error description The description of the error. Possible

values are:

v Unkwown status in occurrence

record

v IBM Tivoli Workload Scheduler

current plan status in not active


Operator response: If the problem persists, contact

IBM Software Support for assistance.

EEWI27I APPLICATION application WAS

INSERTED IN CURRENT PLAN WITH

INPUT ARRIVAL DATE AND TIME

yymmdd hhmmss

Explanation: There is no further help information

available.

EEWI28W yymmdd hhmmss APPLICATION

application WAS NOT INSERTED IN

CURRENT PLAN WITH INPUT

ARRIVAL DATE AND TIME iadatetime

Explanation: The specified application was not

submitted in the current plan.


application The name of the application that was

not submitted in the current plan.

iadatetime The input arrival date and time.


Operator response: Verify the following:

v The date and time on which you submitted the

application is outside the validity interval specified

when the application was defined.

v The input arrival date and time specified during the

submission is outside the current plan validity

interval.

v You did not already submit this application with the

same input arrival date and time.

EEWI30S yymmdd hhmmss module CA7SPAN MUST

BE 4 DIGITS IN FORMAT HHMM

Explanation: See text.






Operator response: Specify a value for the CA7SPAN

in the correct format and restart the module.

EEWI19E • EEWI30S


EEWI32S yymmdd hhmmss module AT LEAST ONE

INTERFACE MUST BE DIFFERENT

FROM NODE

Explanation: All the interfaces, CA-7, TWS for z/OS

and JES are set to NO. One must be set to YES,

otherwise the access method has no interface with

which to communicate.






Operator response: Specify a value other than NO for

at least one of the parameters: CA7INTERFACE,

JESINTERFACE, and OPCINTERFACE and restart the started

task.

EEWI33W yymmdd hhmmss TASK task

APPLICATION application CANNOT BE

INSERTED IN THE CURRENT PLAN

Explanation: The occurrence could not be inserted in

the current plan of Tivoli Workload Scheduler for

z/OS.


task The name of the task that issued the

message.

application The name of the application that was

submitted in the current plan.


Operator response: Define the application correctly in

the Tivoli Workload Scheduler for z/OS database and

restart the request.

EEWI34W APPLICATION application CANNOT BE

INSERTED IN THE CURRENT PLAN

Explanation: The occurrence could not be inserted in

the current plan of Tivoli Workload Scheduler for

z/OS.

Possible reasons are:

v The application is not defined in the Tivoli Workload

Scheduler for z/OS Application Description database

v The application valid-from date is later than the

current plan end date


Operator response: Define the application correctly in

the Tivoli Workload Scheduler for z/OS database and

restart the request.

EEWI35W JCL dataset(member) NOT FOUND

Explanation: The indicated JCL was not found in the

JCL library.

dataset The name of the data set that was expected to

contain the JCL.

member The name of the member containing the JCL.


Operator response: Define the JCL in the correct

member of the data set and restart the request.

EEWI36W yymmdd hhmmss IA AND IATIME

CANNOT BE SPECIFIED TOGETHER

Explanation: Both the IA and the IATIME parameters

were supplied in the task definition.



Operator response: Reissue the request, supplying

only one of the indicated parameters.

EEWI37W yymmdd hhmmss DEADLINE AND

DEADLINETIME CANNOT BE

SPECIFIED TOGETHER

Explanation: Both the DEADLINE and the

DEADLINETIME parameters were supplied in the task

definition.



Operator response: Reissue the request, supplying

only one of the indicated parameters.

EEWI38I jobname (jobid) n1 n2 result restype


jobid The identifier of the job.

n1 The number of seconds passed from the

request.

n2 The number of seconds of CPU time

consumed.

result Can be one of the following values:

ABEND

If the job ends abnormally. In this case

restype can be:

Sxyz System Abend

Unnnn User Abend

CONDCOD

The job does not end successfully due to

the condition code of one step that does

not match the definition. In this case restype

EEWI32S • EEWI38I


|||

|||

|||

|

||

||

|

|||

contains: the RC=nnnnn value of the return

code of the last step that was run, if

LASTSTEP specified, or of the worst step

that does not match the definition of the

job on the distributed side.

EXEC

If the job is running or is in the input

queue.

JCLERRO

If the job failed due to a JCL error.

SUCCES

If the job completed successfully.

UNKNOWN

If the job ID is unknown.

blank

In case of an internetwork dependency

when the manual submission was not

performed.

EEWI42I yymmdd hhmmss TASK task MODULE

EEWTCP65 ISSUED, MACRO 'EZASMI

TYPE=GETPEERNAME' NEAR LABEL

'M2505710' TO GET PEER ADDRESS =

address



task The name of the task.

address The address of the remote partner.

EEWI42I


||||||

|

||

||

||

PeopleSoft access method messages - N

This section lists error and warning messages that might be issued by the

PeopleSoft access method processes.

Note: In addition to these messages, the PeopleSoft access method also issues

messages which it shares with Tivoli Workload Scheduler for Visualized

Data Centers, and which are listed under the product code HTW and the

component code GT (see “PeopleSoft access method messages - HTWGT” on

page 314).

EEWN0070E The connection to the server "server" for

user "user" has failed.

Explanation: The connection to the PeopleSoft

application server could not be made or has failed. This

can be due to any of the following reasons:

v The PeopleSoft user ID, or its password, or both, are

incorrectly specified in the options file

v The PeopleSoft application server IP address or host

name, or its port number, or both, are incorrectly

specified in the options file

v The PeopleSoft application server refused the

connection.

v A network failure occurred.

System action: The PeopleSoft process cannot be

submitted and monitored.

Operator response: Verify that the values in the

options file for the PeopleSoft user, its encrypted

password, the application server address, and the

application server port are correct.

If the option values are correct, then analyze the

PeopleSoft application server log for the failed

connection attempt.

When you have found the problem, correct it and retry

the operation.

EEWN0100W Option "lower_option(lower_option_value)"

must have a value not greater than

option "higher_option(higher_option_value)".


System action: The program continues, using the

default values for these options.

Operator response: If you do not want to use the

default values, stop the program, change the options so

that the value of the lower_option is not greater than the

value of the higher_option, and restart the program.

EEWN0101W Option "option(value)" is not a positive

value.

Explanation: The indicated option must have a

positive value.


default values for this option.


default values, stop the program, change the option to

a positive value and restart the program.

EEWN0102W Option "option(value)" is greater than

the maximum value allowed

(maximum_value).



default values for this option.


default values, stop the program, change the option to

a value not greater than the maximum allowed, and

restart the program.

EEWN0104E The method failed to submit and

monitor the PeopleSoft process to

completion due to a connection failure.


System action: The Tivoli Workload Scheduler job is

put into the "abend" status.

Operator response: Check the values of the options

that define the connection (application server name or

IP address, application server port, user ID, and

password). If the values are correct, check if there were

network failures at the time of the submission. When

you have identified and fixed the problem, run the

Tivoli Workload Scheduler job again.

EEWN0105E The process submission failed due to a

conflict in the PeopleSoft database. The

submission was tried number_of_tries

times.

Explanation: The access method was unable to submit

the PeopleSoft process. No further submission attempts

will be made because the maximum number of retries

(tws_retry option value) has been reached. The error

was due to an unmanaged conflict between concurrent

database save operations in PeopleSoft. This might

occur when several Tivoli Workload Scheduler jobs

submit the same PeopleSoft process, and that process

uses inline bind variables.

EEWN0070E • EEWN0105E


System action: The PeopleSoft process could not be

submitted. The Tivoli Workload Scheduler job is put

into the "abend" status.

Operator response: Rerun the Tivoli Workload

Scheduler job. If the problem persists, contact IBM


EEWN0106E The process submission has failed for

an unknown reason.




Operator response: Check the Tivoli Workload

Scheduler job definition. Check that all parameters are

correct and that the referred objects all exist. Retry the

operation. If the problem persists, contact IBM Software


EEWN0107E The monitoring of the PeopleSoft

process has failed.




Operator response: Monitor the PeopleSoft process in

the PeopleSoft Process Monitor page.

EEWN0110W The process submission has failed due

to a conflict in the PeopleSoft database.

The submission is retried until the

maximum number of retries is reached.


System action: The program tries to resubmit the

PeopleSoft process until the maximum number of

retries is reached (the value of the tws_reply option).


EEWN0111E The submission, control, or monitoring

of the PeopleSoft process has failed for

an unknown reason. The access method

does not attempt to resubmit it.




Operator response: Retry the operation. If the

problem persists, contact IBM Software Support for

assistance.

EEWN0112E The process submission attempt failed

due to a possible connection failure.




Operator response: Check the values of the options

that define the connection (application server name or

IP address, application server port, user ID, and

password). If the values are correct, check if there were

network failures at the time of the submission. When

you have identified and fixed the problem, run the

Tivoli Workload Scheduler job again.

EEWN0113W The attempt to monitor the progress of

the PeopleSoft job has failed. The

attempt is retried until the maximum

number of retries is reached.


System action: The program tries to monitor the

PeopleSoft process until the maximum number of

retries is reached (the value of the tws_reply option).


EEWN0119E The retrieved run status (status) has an

incorrect format.




Operator response: Resubmit the PeopleSoft process.

If the problem persists, contact IBM Software Support

for assistance.

EEWN0120E An internal error "exception" has

occurred. The error message is:

"exception_message".




Operator response: Resubmit the PeopleSoft process.


for assistance.

EEWN0106E • EEWN0120E


SAP R/3 access method messages - O

This section lists error and warning messages that might be issued by the SAP R/3

access method processes.

EEWO0001E Job aborted.


System action: R3batch stops.

Operator response: This is an internal error. Retry the

operation (the error might be transient). If the problem

persists, contact IBM Software Support for assistance.

EEWO0010E The extended agent has not started. The

command to launch it included no

options.


System action: R3batch stops

Operator response: See the User’s Guide for a list of

the parameters you can specify with the r3batch

command. Reissue the command with the correct

parameters.


syntax.

EEWO0011E The extended agent has not started. The

command to launch it has syntax errors.



Operator response: See the User’s Guide for a list of

the parameters you can specify with the r3batch

command. Reissue the command with the correct

parameters.

See also: The User’s Guide for details about the

command syntax.

EEWO0012E The extended agent could not be

initialized.



Operator response: Check that the connections

between the SAP system and the local host are correct.

Check also that the local options file exists, is in the

correct directory, has read permission for the user

running r3batch, and is not corrupt. When you have

found and corrected the error, rerun r3batch.

EEWO0013E The extended agent could not find the

following Tivoli Workload Scheduler

home directory: TWS_home_directory.

Explanation: TWS_home_directory is the directory

where Tivoli Workload Scheduler is installed.


Operator response: Check that the directory indicated

in the message has the correct name, that it exists, and

that it has read permission for the user running

r3batch. When you have found and corrected the error,

rerun r3batch.

EEWO0014E The extended agent could not find the

following method options file:

method_options_file.

Explanation: method_options_file is the file that contains

the R/3 method options.


Operator response: Check that the file indicated in the

message has the correct name, that it exists, and that it

has read permission for the user running r3batch. If the

file is missing, follow the instructions that describes

how to create it in the User’s Guide. When you have

found and corrected the error, rerun r3batch.

See also: The User’s Guide for the instructions on how

to create the method options file.

EEWO0015E The method options file:

method_options_file for the following job:

job_name does not contain the required

options.



job_name is the name of the job that you are trying to

run.


Operator response: Check in the User’s Guide for

details about the options that must be supplied for the

job that you want to run. When you have found and

corrected the error, rerun r3batch.


options you must include in the method options file for

each type of job.

EEWO0016E The method options file:

method_options_file for the following job:

job_name does not contain all of the

required options.



EEWO0001E • EEWO0016E


job_name is the name of the job that you are trying to

run.


Operator response: Check in the User’s Guide for

details about the options that must be supplied for the

job that you want to run. When you have found and



options you must include in the method options file for

each type of job.

EEWO0017E An internal I/O error occurred reading

the following method options file:





Operator response: Check the following:

v The file system where the method options file is

located has enough memory available.

v The file has read permission for the user that is

running r3batch.

v The operating system has not reached the maximum

number of files it can have open at the same time.

When you have found and corrected the error, rerun

r3batch.

EEWO0018E An internal I/O error occurred reading

the following method options file:






v The file system where the method options file is

located has enough memory available.

v The file has read permission for the user that is

running r3batch.

v The operating system has not reached the maximum

number of files it can have open at the same time.

When you have found and corrected the error, rerun

r3batch.

If the error persists, contact IBM Software Support for

assistance.

EEWO0019E An internal error occurred while trying

to initialize the TWSMETH_CP code

page.



Operator response: This is an internal error. Contact


EEWO0020E An internal error occurred while trying

to decrypt the R/3 password.





EEWO0030E An error occurred while trying to

convert a timestamp read from SAP R/3

system.



Operator response: Check the timestamp on SAP R/3

is valid.

EEWO0031E The value EIF_Port_Number is not a

valid EIF port number.


System action: The program stops.

Operator response: Specify a valid port number, in

the range 0 - 65535.

EEWO0032E Cannot open the event configuration file

CFG_File.



Operator response: Verify that the file exists and is

readable.

EEWO0033E Cannot create the PID file for the

extended agent XA_Workstation_Name.



Operator response: The monitoring process was

unable to create the file in which to store the PID

number. For detailed information, see the trace file for

the XA workstation indicated in the message.



EEWO0034E An internal error occurred while parsing

the event configuration file for the

XA_Workstation_Name workstation.





EEWO0035E Monitoring of the XA_Workstation_Name

workstation is already running. Program

exiting.



Operator response: Ensure that only one instance of

the event monitoring runs on one extended agent

workstation.

EEWO0036E The monitoring process failed to

daemonize.



Operator response: For detailed information, see the

trace file for the XA workstation indicated in the

message.

EEWO0037E An error occurred: Parameter EIFSRV is

missing.



Operator response: Specify the parameter EIFSRV on

the command line.

EEWO0038E An error occurred: Parameter EIFPORT

is missing.



Operator response: Specify the parameter EIFPORT

on the command line.

EEWO0100E An internal error has occurred. The

following unknown BAPI return code:

BAPI_return_code (BAPI_message) was

received while calling the following

function: function.

Explanation: BAPI_return_code is the code returned by

the BAPI module.

BAPI_message is the message associated with the code

returned by the BAPI module.

function is one of the functions used by the program.




EEWO0101E The following ABAP module cannot be

found: "ABAP_module". All required

ABAP modules must be installed before

running the extended agent.

Explanation: ABAP_module is a required module that

has not been installed.


Operator response: Use the User’s Guide to determine

the ABAP modules required. Contact your SAP system

administrator to have them installed.

See also: The User’s Guide for details about the ABAP

modules required.


function ItCreate has failed for the

following object: object in the following

module: module.

Explanation: object is the object that the function

ItCreate was trying to perform on.

module is the module being processed.




EEWO0103E R3batch has run out of memory (the

function RfcAllocParamSpace has failed

in the following module: module).

Explanation: module is the module being performed.



1. Verify if the workstation has enough memory

available. Information about the memory

requirements of Tivoli Workload Scheduler for

Applications is provided in the Download Document.

If not, you might need to increase the memory of

the workstation or make changes in memory

management and paging to make more memory

available to r3batch. Rerun r3batch.

2. If the workstation memory is adequate, try closing

all the applications that you do not need, and then

rerun r3batch.

3. If the problem persists, reboot the workstation, and

then rerun r3batch.

4. If the problem persists, contact IBM Software




See also: The Download Document for details about

memory requirements.

EEWO0104E An internal error has occurred. The RFC

system failed while calling the

following module: module.

Explanation: module is the module being performed.




EEWO0107E This extended agent for R/3 does not

support your version of the SAP R/3

system, which is the following:

R/3_version.

Explanation: R/3_version is the version number of the

SAP R/3 system on this workstation.


Operator response: See the User’s Guide to determine

the versions of SAP supported. If you are using a lower

version of SAP than those supported, upgrade to a

supported version. If you are using a higher version of

SAP than those supported, check on the IBM products

Web site to see if there is a later version of Tivoli

Workload Scheduler for Applications available.


versions of SAP that are supported.

EEWO0108E R3batch has found that the following

component is not at the correct version:

component.

Explanation: component is the component of Tivoli

Workload Scheduler for Applications that is at the

wrong version level.


Operator response: Upgrade the specific component.

If not possible, upgrade or reinstall Tivoli Workload

Scheduler for Applications. See the User’s Guide for

details about the installation.


installation.


following RFC function: function_name

failed after the following number of

attempts: attempts.

Explanation: function_name is the name of the function

being performed.

attempts is a count of the number of tries that r3batch

made at performing the function.




EEWO0110E An internal error has occurred. The RFC

was not initialized when calling the

following function: function_name.

Explanation: function_name is the name of the function

being performed.




EEWO0111E This user cannot define jobs on the

following SAP R/3 system:

SAP_system_name.

Explanation: You do not have the required authority

to define or create jobs on the SAP system.

SAP_system_name is the name of the SAP system where

you do not have permission to define or create jobs.

System action: R3batch continues, but the job you are

trying to run is not processed.

Operator response: Consult your local SAP or Tivoli

Workload Scheduler administrator to determine if the

user ID that you used is the correct one, and if this

user has the authorization to run jobs on the SAP

system. When the problem is resolved restart r3batch.

EEWO0112E The extended agent cannot create the

following job: "job_name" with job ID:

"job_ID".

Explanation: job_name is the name of the job that

cannot be created.

job_ID is the job ID of the job that cannot be created.

System action: R3batch continues, but the job you are

trying to run is not processed. The batch log

(r3batch_trace.log) is produced giving more details

about the steps that occurred before the job creation

failed.

Operator response: Use the batch log to determine the

cause of the problem.

If the log file does not contain enough information, set

the debug_level to MAX as described in the User’s

Guide. Then rerun r3batch.

When you have located and resolved the problem,

rerun r3batch.

EEWO0113E An internal error has occurred. An

exception: exception_number has occurred

while calling the following function

module: function_module_name.

Explanation: exception_number is the error number.



function_module_name is the name of the function

module being performed when the error occurred.


Operator response: This error might not be repeated.

Try restarting r3batch. If the error persists, contact IBM



following database name is not correct:

database_name. The help view is not

retrieved.

Explanation: database_name is the database name that

is not correct.





EEWO0115E An internal error occurred. The

following counter ID is not valid:

counter_ID.

Explanation: counter_ID is the counter ID that is not

valid.





EEWO0116E The extended agent could not open the

following joblog (stdlist) file:

joblog_file_name.

Explanation: Another process has locked the joblog

file.

joblog_file_name is the name of the file that is locked.

System action: R3batch continues.

Operator response: Take these steps.

v Use the operating system facilities to determine

which process has locked the joblog file.

v Wait until the process that has locked the file stops.

v If the process does not stop in an acceptable time

frame, consider forcing it to stop (you should

evaluate the risk of leaving data in a corrupted

state). Use the operating system facilities to

accomplish this.

EEWO0117E R3batch has failed because the

workstation where it is running has

insufficient memory.




1. Verify if the workstation has enough memory

available. Information about the memory

requirements of Tivoli Workload Scheduler for

Applications is provided in the Download Document.

If not, you may need to increase the memory of the

workstation or make changes in memory

management and paging to make more memory

available to r3batch. Rerun r3batch.

2. If the workstation memory is adequate, try closing

all the applications that you do not need, and then

rerun r3batch.

3. If the problem persists, reboot the workstation, and

then rerun r3batch.

4. If the problem persists, contact IBM Software


See also: The Download Document for details about

memory requirements.

EEWO0118E R3batch has failed because it could not

create and start a job instance.


System action: The job instance is not created.

Operator response: Check the r3batch log file for the

reason for the error and try to resolve it. If you have



for assistance.

EEWO0119E An internal error occurred. The cleanup

task could not delete the following job:

"job_name". The job ID is: "job_ID".


cannot be deleted.

job_ID is the job ID of the job that cannot be deleted.





EEWO0120E The job you are trying to monitor does

not exists. The job number and name

are as follows: "job_number: job_name".

Explanation: job_number is the job number of the job

that does not exist.

job_name is the name of the job that does not exist.

System action: The program might stop.

Operator response: Verify that the job number and job

name you are trying to monitor match an existing job.

To determine which jobs are available, use the Find Job

functionality in the Job Scheduling Console. If you have




EEWO0121E The R/3 system might not be available.

BDCWAIT has failed to start after the

following number of failed attempts: .

Explanation: attempts is the number of times that

r3batch tried to start BDCWAIT.


Operator response: Check that the R/3 system is

running. Check the job status. If you have corrected the

error, rerun r3batch.

EEWO0122E An internal error has occurred. R3batch

could not scan the R/3 joblog for

BDCWAIT messages.


System action: The batch job stops.




could not check the BDC session status

in the R/3 system.


System action: The batch job stops.



EEWO0124E The following SAP R/3 system defined

in the method options file is not

running: SAP_system_name.

Explanation: SAP_system_name is the name of the SAP

R/3 system that is not running.


Operator response: Verify that the information in the

options file is correct. Check that the SAP system is

available, for example, by pinging the IP address of the

SAP system. If you have corrected the error, rerun

r3batch.

EEWO0125E The SAP job specified in the job

definition cannot be performed, because

it has an incorrect job type.


System action: R3batch continues, but the job being

processed is ignored.

Operator response: Check that the SAP job name

specified in the job definition is correct and matches

with the name of the SAP job defined in the SAP

system. Check that the job type is correct. If you have


EEWO0126E The following mapping file cannot be

read due to an I/O error:

mapping_file_name.

Explanation: mapping_file_name is the name of the

return code mapping file that cannot be read.

System action: The job processing continues, but the

return code mapping is not performed.

Operator response: Check that the file with the

indicated name exists, in the correct directory, and with

read permission for the user running r3batch. Open the

file with a text editor to ensure that it is readable. If

you have corrected the error, rerun r3batch.


following method: "method_name" was

called by the following request:

"request_type", which is currently not

supported by the following module:

module.

Explanation: method_name is the name of the method

being called.

request_type is the type of request being made.

module is the module that does not support this request.





EEWO0161E A syntax error occurred when r3batch

was started. The following task

parameter is unrecognized:

task_parameter.

Explanation: task_parameter is the task parameter that

is not recognized.


Operator response: See the User’s Guide for a list

parameters you can specify with the r3batch command.

Reissue the command with the correct parameters.


command syntax.


was started. One or more parameters is

missing from the following task:

task_name. It needs the -c, -j, -l, -t, and

’--’ parameters.

Explanation: task_name is the name of the task that

you are trying to run.




Operator response: See User’s Guide for a description

of the task parameters. Rerun r3batch, supplying the

correct task parameters.

See also: The User’s Guide for a description of the task

parameters.




task_name. It needs the -c, -j, -t, and ’--’

parameters.








parameters.




task_name. It needs the -c, -t, and ’--’

parameters.








parameters.




task_name. It needs the -c, -j, -l, -o, -t, and

’--’ parameters.








parameters.

EEWO0166E An internal error has occurred: GI and

PI require task specification.





EEWO0167E An error occurred when r3batch was

started. One or more internal parameters

is missing from the following task:

task_name. It needs the following

parameter: parameter_name.

Explanation: task_name is the name of the task being

run.

parameter_name is the name of the missing internal

parameter.




EEWO0171E You have specified a step to run an

ABAP or an external program, but the

step number (step_number) cannot be

determined.

Explanation: step_number is the number of the step

that is not in the correct format to be determined.


Operator response: See the SAP system administrator.

EEWO0172E You have defined a job as a series of

steps, but one of the steps has a number

which is out of range: step_number.


that is not in the correct range.


Operator response: See the SAP system administrator

and determine the correct step number.

EEWO0173E You have specified a step to run the

following ABAP: ABAP_name which

requires one or more variants, but no

variants have been specified.

Explanation: ABAP_name is the name of the ABAP

module which is specified to be run.


Operator response: Determine the correct variants to

use from the SAP system administrator. Change the job

specification to add the variant or variants. If a variant

is missing it must be created. There are two alternative

ways to create a variant:



v Follow the instructions in the User’s Guide to create

a variant using the Job Scheduling Console

v Ask the SAP system administrator to create the

variant using the SAP GUI.

EEWO0174E An internal error occurred while

accessing the variant selection table

J1O1VARSO for the following report:

"report_name" and variant: "variant_name".

Explanation: report_name the name of the report that

r3batch was trying to create.

variant_name the name of the variant that was being

processed when the error occurred.

System action: R3batch continues, but the job is not

processed.

Operator response: Rerun r3batch (the problem might

be transient). If the problem persists, contact IBM



accessing the variant counter table

J1O1VARCO for the following report:

"report_name" and variant: "variant_name".






processed.

Operator response: Rerun r3batch (the problem might

be transient). If the problem persists, contact IBM


EEWO0176E There is an error in the job information

that has prevented the r3batch program

from creating the following step:

step_number.

Explanation: You are trying to add a step but an error

in the step data prevents it from being added.

step_number is the number of the step you are trying to

add.

System action: The step is not added.

Operator response: Verify the correctness of the

information in the step, such as the name of the job, the

user name, and the variant details, correct any errors

and retry the add step action. If the problem continues,

also check the connectivity with the SAP system. If you

find the problem and correct it, rerun r3batch.

EEWO0177E The following step is not valid, and

cannot be performed: step_number.


that is not valid.

System action: R3batch continues, but the step is not

performed.

Operator response: Verify the correctness of the

information in the step. Verify the name of the job, the

user name, and the variant details . If the problem

continues, also check the connectivity with the SAP

system. If you find the problem and correct it, rerun

r3batch.


following incorrect step type: "step_type"

has been supplied for step:

"step_number".

Explanation: step_type is the non-valid type that has

been supplied by the GUI for the step.

step_number is the number of the step being processed.

System action: R3batch continues, but the step is not

performed.



EEWO0179E An internal error occurred because a

variant name counter field was missing

for the following report: "report_name"

and variant: "variant_name".









EEWO0180E During the preparation of the following

report: "report_name", r3batch could not

make a copy of the following variant:

"original_variant_name" because the copy

name of the variant generated

automatically by the program:

"variant_copy_name" is the same as that of

an existing variant.



original_variant_name the name of the variant that was

being processed when the error occurred.

variant_copy_name the name of the copy that r3batch is



trying to create. It is also the name of the existing

variant.


Operator response: Take either of these steps:

v Change the name of the existing variant with the

same name.

v Change the name of the original variant which was

being copied (the copy name is based on the original,

so any change in the original name will create a copy

with a different name).

Rerun r3batch.

EEWO0181E R3batch could not obtain the semaphore

identified in the global options file

(required to control access to shared

resources).


System action: R3batch continues, but the variant is

not processed.

Operator response: Contact the SAP system

administrator to determine why the semaphore is

missing. If you find the problem and correct it, rerun

r3batch.

See also: See the User’s Guide for more information

about variants and semaphores.

EEWO0182E R3batch could not create the following

report: "report_name" because the variant:

"variant_name" has one or more incorrect

values (placeholders or counters).





System action: R3batch continues, but the report is

not created.


administrator to determine why the values are

incorrect, and to correct them. If you find the problem

and correct it, rerun r3batch.

EEWO0183E An internal error has occurred while

calling the function

"j_1O1_variant_maintain_sel_tbl",

because the parameters to the call were

not valid.






EEWO0184E A variant required for this job is locked

by another application.



Operator response: User the operating system tools to

determine which application has locked the variant.

Decide whether to stop that application or wait for it to

stop or unlock the variant itself. If you find the

problem and correct it, rerun r3batch.

EEWO0185E The properties of the variant required

for this job indicate that is protected by

another user.


System action: R3batch continues, but the processing

of the job stops.

Operator response: Request the user that protected

the variant to remove the protection so that you can

use it for your job. If you find the problem and correct

it, rerun r3batch.

EEWO0186E A variant required for this job no longer

exists.



Operator response: Check in the job definition that

the variant is correctly specified. If it is not, correct the

job definition and rerun r3batch. If it is correctly

specified, the variant is missing and must be created.

There are two alternative ways to create a variant:





When the job definition is pointing to an existing

variant, rerun r3batch.

EEWO0187E A variant required for this job is

obsolete and cannot be used.



Operator response: Check in the job definition that

the variant is correctly specified. If it is not, correct the

job definition and rerun r3batch. If it is correctly

specified, change the variant specification to refer to a

variant that is not obsolete or create a new variant.

There are two alternative ways to create a variant:







When the job definition is pointing to an existing,

non-obsolete variant, rerun r3batch.

EEWO0189E A variant required for this job cannot be

created. The variant data is not valid

(too long): variant_data.

Explanation: variant_data is the data used to create a

variant that is too long.


Operator response: Check the data used to create the

variant. If you find an error and correct it, rerun

r3batch.

EEWO0223E Either no matching job could be found

in the following R/3 instance:

R/3_instance, or a job is found with steps

but no start time.

The following identify the job:

Host: host_name

Job: job_name

User: user_name

Client: client.

Explanation: You have probably supplied incorrect

information to describe the R/3 job.

host_name is the name of the SAP system host.

job_name is the name of the job for which a match

cannot be found on the R/3 system.

user_name is the name of the user running the job.

client identifies the R/3 client.


Operator response: Check whether there is a job on

the SAP system which has a matching R/3 client, job

name and user name as the Tivoli Workload Scheduler

for Applications job definition for this job. Also verify

that the R/3 transaction SM37 shows the job in the

"released" state.

When you have identified the error, correct the Tivoli

Workload Scheduler for Applications job definition and

rerun r3batch.

EEWO0224E R3batch cannot perform a job because it

has the same job name user name and

client number as an existing job.



Operator response: Check if you have tried to

accidentally run the same job twice. If you need to run

this job, either wait for the previous job to finish, or

contact the SAP system administrator to stop the

previous job. Then rerun r3batch.


recovery process has started with a

non-valid or missing batch job ID:

job_ID.

Explanation: job_ID identifies the job that cannot be

processed.

System action: The recovery process does not

continue. The job recovery is not performed.




recovery process has started with a

non-numeric or wrong-length batch job

ID. It must be an eight digit number:

job_ID.

Explanation: job_ID identifies the job that cannot be

processed.





EEWO0262E A syntax error has been found with the

job options. The following option does

not start with a hyphen: job_option.

Explanation: job_option is the option that does not

start with a hyphen.


Operator response: Check the job option syntax in the

User’s Guide. Correct the syntax and rerun r3batch.

See also: The User’s Guide for details about the job

options syntax.


job options. More job options were

submitted than the maximum allowed:

maximum_job_options.

Explanation: maximum_job_options is the maximum

number of job options that you can define.



User’s Guide. Reduce the number of job options for this

job, for example, by dividing it into two jobs, each of

which would have a reduced number of job options.

Correct the syntax and rerun r3batch.


options syntax.




job options. The following job option

requires a value after keyword:

job_option.

Explanation: job_option is the option that requires a

value.



User’s Guide. Correct the syntax by adding the value to

the indicated option and rerun r3batch.


options syntax.


job options. The following option

sequence is not correct: "job_option1"

"job_option2". The "job_option3" option

requires a value, which cannot begin

with a hyphen (minus sign).

Explanation: There is a problem with the syntax of the

job options. The above message might exactly explain

the problem. However, it might be that an error of

syntax has allowed the program to interpret a value as

a job option.

job_option1, is the option that must not precede

job_option2.

job_option3 requires a value, which cannot commence

with a hyphen.


Operator response: Check the full job option syntax in

the User’s Guide, not only for the indicated job options,

but also for all others. Correct the syntax and rerun

r3batch.


options syntax.


job options. The following option could

not be recognized:

unrecognizable_job_option.

Explanation: unrecognizable_job_option is a string that

by its position in the syntax and the presence of a

hyphen in the first position indicates that it is a job

option, but that does not match a valid job option.



User’s Guide. Correct the syntax and rerun r3batch.


options syntax.


job options. The following job ID is not

valid: job_ID.

Explanation: job_ID is the job ID that is not valid.



User’s Guide. Correct the job ID and rerun r3batch.


options syntax.


recovery process has started with the

following non-valid parameter:

parameter.

Explanation: parameter is the non-valid parameter of

the job that cannot be processed.






job options. The following option:

"job_option" has a non-valid value:

"option_value".

Explanation: job_option is the option that has a

non-valid value.

option_value is the value that is not valid.



User’s Guide. Correct the syntax by changing the value

of the indicated option so that it is valid and rerun

r3batch.


options syntax.



"job_option" has a non-valid value for the

variant selection option sign:

"option_value". The value must be one of

the following: "valid_values".


non-valid value.

option_value is the value that is not valid for the variant

selection option sign.

valid_values is a list of the permitted values for the

option in this context.







r3batch.


options syntax.



"job_option" has a non-valid value for the

variant selection option operation:

"option_value". The value must be one of

the following: "valid_values".


non-valid value.

option_value is the value that is not valid for the variant

selection option operation.

valid_values is a list of the permitted values for the

option in this context.





r3batch.


options syntax.

EEWO0383E R3batch failed to connect to the R/3

system on the following host:

"host_name", after the following number

of attempts: attempts.

Explanation: host_name is the workstation where

r3batch cannot connect to the R/3 system.

attempts is the number of times that r3batch has tried.


Operator response: The problem might have one of

two causes:

v Check that the client number, R/3 user ID, and

password in the options file are correct.

v Check with the SAP system administrator that the

XA for SAP function modules (the programs for the

Tivoli Workload Scheduler Xagent feature) have been

installed and activated on the host

If you have resolved the problem, rerun r3batch.

EEWO0384E R3batch failed to establish a connection

to the following R/3 instance:

"R/3_instance" on the following host:

"host_name", after the following number

of attempts: attempts.

Explanation: R/3_instance identifies the R/3 instance

that could not be connected to.

host_name is the workstation where r3batch cannot

connect to the R/3 system.

attempts is the number of times that r3batch has tried.


Operator response: The problem might have one of

two causes:

v Check that the client number, R/3 user ID and

password in the options file are correct

v Check with the SAP system administrator that the

indicated R/3 instance is running on the host

If you have resolved the problem, rerun r3batch.


either could not open or could not copy

the R/3 job.



Operator response: The problem might be one of

several:

v Check that there is available disk space in the file set

where Tivoli Workload Scheduler for Applications is

installed. If there is not sufficient space, create more

space and rerun r3batch.

v Check that the user running r3batch has read and

write permissions in the Tivoli Workload Scheduler

for Applications install directory and its

subdirectories. If there is a problem with

permissions, correct it and rerun r3batch.

v Check that the operating system has not reached the

maximum number of files that it can open at the

same time. If this is the problem, either use the

operating system facilities to allow more file

descriptors, wait for other applications that are using

files to close them, or stop other applications that are

using files. Rerun r3batch.

v If the problem is not one of these, contact IBM


EEWO0422E The following variant option is not

valid: variant_option

Explanation: variant_option is the variant option

(parameter) that is not valid.



administrator to determine the correct format and value

for the indicated variant option. Correct the job

definition and rerun r3batch.



EEWO0426E R3batch cannot create the job. The

following R/3 RFC user does not have

the appropriate R/3 user authorization to

create and start batch jobs: user_name.

Explanation: user_name identifies the user that does

not have R/3 authorization to create and start batch

jobs.


Operator response: Either contact the SAP system

administrator to have the appropriate authorizations

given to the indicated user, or change the RFC user in

the job definitions to a user that has the required

authorizations. Rerun r3batch.


program could not create the temporary

variant table for this job (the rowptr

from ItAppline is null).





EEWO0429E The following job was not found, or is

not in a correct state: "job_name" with the

following job ID: "job_ID". The state

must be shown in R/3 as "Scheduled",

not "Released" or "Finished".

Explanation: job_name and job_ID identify the job that

was not found, or is not in a correct state.


Operator response: Check that the job has been

correctly defined in the job definitions. Contact the SAP

system administrator to determine the correct

identification of the R/3 job, and that it exists, and that

it is in one of the above-indicated statuses. Correct the

problem and rerun r3batch.

EEWO0439E The required options are not specified

either in the global or in the local

options file.

Explanation: The action being performed by the

r3batch x-agent running the SAP job needs the values

of one or more specific options that it expects to find in

the global or local option file. It could not find those

options. The details about which options are required

are given in the User’s Guide. Some options are

mandatory for all actions while other options are

action-specific.

System action: The program continues, if possible,

ignoring the action that encountered the error.

Operator response: Check in the User’s Guide to

determine the required options. Amend the global or

local options file (or both) to include those options.

Rerun r3batch.

EEWO0441E The following client number is not

valid: "client_number". Client numbers

must be between 0 and 999.

Explanation: client_number is the client number (SAP

port number) that is not an integer between 0 and 999.



administrator to determine the correct value (the port

number) of the R/3 client. Check that the client option

in the global or local options file has this value,

changing it if not. For more details about the options in

the global and local options files see the User’s Guide.

Rerun r3batch.

See also: The User’s Guide for more details about the

options in the global and local options files.

EEWO0450E The year number "year_number" of

keyword "keyword" is not valid: . Year

numbers must be 4 digit numeric

values.

Explanation: The year_from or year_to keyword was

set to a value thatis not valid. The value for the year

must be specified in the format yyyy.


Operator response: Change the value of the indicated

keyword to be a four-digit number and rerun the

command.


values allowed for the indicated keywords.

EEWO0451E R3batch could not create the file or

directory: "filename". Either the filename

is not valid or access rights are missing.

Explanation: Either the specified filename is not in the

correct format or r3batch does not have the access

rights to create the file or directory.


Operator response: Do one of the following and rerun

the command:

v Contact your system administrator to change the

access rights of the desired location so that r3batch is

authorized to create and edit the file or directory in

the path you want.

v Change the path of the indicated filename to a

location where r3batch is authorized to create and

edit files.





EEWO0452E The supplied year range is not valid.

The from year:"year_from" is greater than

the to year:"year_to".

Explanation: The date set for the year_from keyword

is later than the value set for the year_to keyword.


Operator response: Correct the year range so that the

starting year is earlier than the ending year.



EEWO0453E R3batch could not create the following

directory: "directory". Either the directory

name is not valid or "r3batch" does not

have access rights required to create the

file or directory.



Operator response: Do one of the following and rerun

the command:

v Contact your system administrator to change the

access rights of the desired location so that r3batch is

authorized to create and edit the directory in the

path you want.

v Change the path to a location where r3batch is

authorized to create and edit files.



EEWO0460E The SAP system does not have the

correct XBP interface version. The XBP

interface version must be 2.0 or later.



Operator response: Choose a SAP system with the

correct XBP interface version.

EEWO0461E An internal error occurred during an

external dependency operation.





assistance.

EEWO0462E R3batch could not commit the external

dependency on the SAP system. Event

name: "event_name". Event parameter:

"event_parameter".

Explanation: The request to commit the external

dependency, identified by the SAP event name and

parameter indicated in the message, failed on the target

SAP system.


Operator response: Do one of the following:

v Check the log file for preceeding error messages.

v Contact your system administrator to validate the

XBP event history.

v Retry the operation. If the problem persists, contact


See also: The User’s Guide for more details about

using SAP background processing events as external

dependencies.

EEWO0504E An internal error has occurred: (RFC

failed: SXMI_LOGON).







failed: SXMI_VERSIONS_GET).







failed: SXMI_LOGON).







failed: SXMI_AUDITLEVEL_SET).








EEWO0510E An internal error has occurred:

(get_record: Non-valid keyword.

Expected: expected_keyword).

Explanation: expected_keyword is the keyword expected

at this point.





EEWO0550E No job name has been specified for the

following user: user_name.

Explanation: user_name identifies the user for which a

job name has not been specified.

System action: The program waits for you to correct

the input or exit.

Operator response: Supply a job name and continue.

EEWO0551E Either no matching job could be found,

or a job is found with steps but no start

time, or the job that is found has a

"released" status.

The following identify the job:

User: user_name

Job: job_name.

Explanation: user_name identifies the user for which

the job cannot be run.

job_name identifies the job that cannot be run.


the input or exit.

Operator response: Check whether the R/3 job name

and user name match the Tivoli Workload Scheduler

for Applications job definition for this job. Check if the

R/3 transaction SM37 shows the job in the "released"

state; as SAP jobs in the "released" state cannot be run.

Correct the problem and continue.

EEWO0552E The R/3 job scheduling system has

found an error for the following job:

User: user_name

Job: job_name.

Explanation: user_name identifies the user for which

the job cannot be run.

job_name identifies the job that cannot be run.


Operator response: Contact the R/3 system

administrator to check the R/3 syslog, which should

contain more details about the error. Also check the

correctness of the indicated user name and job name.

Correct the problem and rerun r3batch.

EEWO0553E The XBP interface has returned the

following error: "The external user is

missing."






EEWO0554E R3batch has stopped because the R/3

XMI logging mechanism has returned

an error. There might be a connection

problem.



Operator response: Check that the connection with

the R/3 system is working correctly. If it is, or if the

error persists, contact IBM Software Support for

assistance.

EEWO0555E R3batch could not invoke the R/3 XMI

interface. There might be a connection

problem.






following error: "Cannot select the

following job: job_name with the

following job ID: job_ID".


cannot be selected.

job_ID is the ID of the job that cannot be selected.


Operator response: Check that the job name and ID

are correctly identified in the job options. Ensure they

match with the R/3 job. Correct any error you find and

rerun r3batch, otherwise contact IBM Software Support

for assistance.


following error: "Cannot process the job

because the job name or job ID is

missing.".







match with the R/3 job. Correct any error you find and

rerun r3batch, otherwise contact IBM Software Support

for assistance.


following error: "Cannot delete the

following job:".

Job name: "job_name"Job ID: "job_ID".


cannot be deleted.

job_ID is the ID of the job that cannot be deleted.




match with the R/3 job. Contact the R/3 system

administrator to check the R/3 syslog, which should

contain more details about the error. Check that the

user has the correct permission to run the job.

Correct any error you find and rerun r3batch,

otherwise contact IBM Software Support for assistance.


following error: "The ABAP program

name is missing."



Operator response: Check the ABAP program name in

the job definition.




following error: "The archive

information cannot be found."






following error: "The supplied print

parameters are not valid."



Operator response: Check the print parameters in the

job definition (see the User’s Guide for details.



See also: The User’s Guide for details about the print

parameters.


following error: "The supplied archive

parameters are not valid."





EEWO0566E The target host name is required for

external step definition.

Explanation: You have defined a job with an external

step, but the target host name is missing in the step

definition.


the input or exit.

Operator response: Specify the host name or exit.

EEWO0568E The following job cannot be started

"immediately":

Job name: "job_name"Job ID: "job_ID".

Explanation: The indicated job has been defined to

run immediately, but the job has dependencies that

cannot be resolved immediately.

job_name is the name of the job that cannot be run

immediately.

job_ID is the ID of the job that cannot be immediately.


Operator response: Check that the job definition

settings of an "immediate" run time and dependencies

is correct. If not, correct the job definition and rerun

r3batch.

If the settings are correct, decide whether you want to

wait for the dependencies to be resolved or delete them

to let the job go ahead. Take the appropriate action and

rerun r3batch.

EEWO0569E An internal error has occurred. The step

count is not correct.








EEWO0570E The following job does not have steps:

Job name: job_name

Job ID: job_ID.

Explanation: job_name is the name of the job that does

not have steps.

job_ID is the ID of the job that does not have steps.

System action: R3batch waits for a response from

you.

Operator response: Edit the job definition to supply

the missing step definitions and continue, or cancel the

job.


count is missing.






EEWO0572E A Process Chain cannot be started.




administrator and verify the SAP log to analyze the

reason for the process chain not starting. If you find an

error in the definition of the process chain in the job

definitions, correct it and rerun r3batch. If the error is

on the R/3 side, wait for it to be fixed and rerun

r3batch.

EEWO0573E The transfer structure for the following

InfoPackage is not yet active:

infopackage_name.

Explanation: infopackage_name identifies the

InfoPackage that cannot be utilized.






request ID could not be found.






EEWO0575E The action has been cancelled for the

following InfoPackage: infopackage_name.


InfoPackage that has been cancelled.





EEWO0576E The job defined in the following

InfoPackage is already running:

infopackage_name.


InfoPackage that is already running.





EEWO0577E The source system of the following

InfoPackage is not correct:

infopackage_name.


InfoPackage with the incorrect source system.





EEWO0578E The following InfoPackage does not

exist: infopackage_name.

Explanation: The probable reason is that the

InfoPackage has been deleted after the job was defined

but before it was run.

infopackage_name identifies the InfoPackage that does

not exist.


Operator response: Check the definition of the

InfoPackage in the job definitions. Ask the R/3 system

administrator to check for its existence in the R/3

system. Correct any error you find and rerun r3batch.

EEWO0579E An internal error has occurred (incorrect

parametrization) while retrieving the list

of available InfoPackages.








EEWO0580E The following InfoPackage cannot be

run as it is already running:

infopackage_name.


InfoPackage that is already running.


Operator response: Check the definition of the

InfoPackage in the job definitions. Check that you are

not trying to run the same job twice. Decide whether

you want to wait for the previous InfoPackage to

finish, or if you want to stop the previous InfoPackage

from running, to allow your job to run. In the latter

case, ask the SAP system administrator to stop the

previous InfoPackage. Rerun r3batch.

EEWO0581E The required Business Information

Warehouse component is not installed

on this R/3 system.




administrator to discuss why the component is not

available. Either have the component installed or

change the job definition to allow the job to run

without this component. Then rerun r3batch.


retrieving the version of the Business

Information Warehouse component.



Operator response: This is an internal error. Check the

log for information that might explain why the version

of the component cannot be retrieved. If you cannot

determine such a reason, contact IBM Software Support

for assistance.

EEWO0583E The required Business Information

Warehouse component is not supported

on this R/3 system level.




administrator to discuss why the component is not

supported. Either have the component upgraded or

change the job definition to allow the job to run

without this component. Then rerun r3batch.

EEWO0584E The following R/3 RFC user does not

have the appropriate R/3 user

authorization to change the status of the

interception or parent-child

functionality: user_name.

Explanation: user_name identifies the user that does

not have the appropriate R/3 user authorization for the

indicated purposes.



administrator to determine if it is possible to change

the RFC user’s permissions on the R/3 system, or

whether you should run this job as a different R/3 RFC

user. In the latter case, modify the job definitions to use

the different RFC user.

Then rerun r3batch.

EEWO0585E The process chain process_chain could not

be scheduled on the SAP BW system.

The R/3 system level does not support

this function.

Explanation: process_chain identifies the process chain

that could not be scheduled on the SAP BW system.



administrator to have the process chain corrected on

the SAP BW system, then run r3batch again.

EEWO0586E The process chain process_chain with log

ID log_id could not be restarted on the

SAP BW system, because of its status.

Only process chains with status

canceled or failed can be restarted.


that could not be restarted on the SAP BW system.

log_id identifies the run instance of the process chain.




the SAP BW system, then run r3batch again.

EEWO0587E The process chain process_chain with log

ID log_id is already running on the SAP

BW system. It cannot be restarted.


that the SAP BW system indicates as running.

log_id identifies the run instance of the process chain.




the R/3 system, then run r3batch again.



1 1 1 1 1

1 1

1

1 1 1

1 1 1 1 1 1

1 1

1

1

1 1 1

1 1 1 1

1 1

1

1

1 1 1


tried to open the file_name file, but the

request failed with return code

return_code.







tried to close the file_name file, but the


return_code.







tried to update the file_name file, but the


return_code.







tried to append records to the file_name

file, but the request failed with return

code return_code.







tried to initialize the module internal

module, but the request failed.







tried to read the file_name file, but the


return_code.






EEWO0700E An internal error has occurred. The job

class is not valid.







print parameters are not valid.







external program flags are not valid.






EEWO0703E The program cannot read the joblog.



Operator response: The problem could have various

causes:

v Check that the user running the job has read

permission for the joblog. Give the user this

permission if it does not.

v Check that there is sufficient disk space in the file

system of the joblog. Make more space available if it

does not.

v Check that the operating system has not reached its

maximum limit of open files. If it has, either extend

this limit, wait for other jobs that are using files to

close, or stop other jobs that are using files.



11111

1

1

111

11111

1

1

111

11111

1

1

111

11111

1

1

111

1111

1

1

111

1 1 1 1 1

1

1

1 1 1

Rerun r3batch.

If none of these actions resolves the problem, contact


EEWO0705E The client number is missing in both

the local and global options files.



Operator response: Check both the local and global

options files in the method directory. Add the client

number (the port of the target host) to one, other, or

both of them, as appropriate. Rerun r3batch.


contents and syntax of the options files.


select process failed.



Operator response: This is an internal error. Check the

log to identify a possible cause. If no cause is evident,

contact IBM Software Support for assistance.


dialog type is not valid.







initial step is not valid.







data is not valid.







EXTCOMPANY and EXTPRODUCT

parameters are different within a

session.






EEWO0711E An internal error has occurred. The start

date is not valid.





persists, check the log to identify a possible cause. If

you identify the problem, correct it and rerun r3batch.

Otherwise, contact IBM Software Support for assistance.


number is not valid.








EEWO0713E The job ID is missing.



Operator response: Check the job definition. If the job

ID is missing, check with the SAP system administrator

to determine the correct ID and enter it in the job

definition. Rerun r3batch.

If the job ID is not missing, this is an internal error.

Retry the operation (the error might be transient). If the


assistance.


joblog name is missing.









failed to close.






EEWO0716E An internal error has occurred. A job

could not be deleted. The following

identify the job:

Job name: job_name

Job ID: job_ID.


could not be deleted.






could not be deleted because it is not

active. The following identify the job:

Job name: job_name

Job ID: job_ID.







EEWO0719E The following job does not exist:

Job name: job_name

Job ID: job_ID.

Explanation: The R/3 job might have been deleted by

a different action, or it might have the correct job name

but an incorrect job ID.

job_name and job_ID identify the job that does not exist.


Operator response: Retry the operation (the error

might be transient). If the problem persists, check on

the SAP system to see if the job exists. If it does not,

check the log to see if it has been deleted by another

action, and if so, decide whether it needs to be rerun.

If it does exist, but has a different job ID from that

indicated in the message, change the job definition

accordingly and rerun r3batch.

In all other circumstances contact IBM Software



could not be submitted. The following

identify the job:

Job name: job_name

Job ID: job_ID.


could not be submitted.







EEWO0724E An internal error has occurred. A file or

database could not be locked.






EEWO0725E The logon has failed. This user is not

authorized to work with the R/3 external

job management system.




administrator to determine if the user can be granted

permission to work with the R/3 external job

management system. If not, rerun the job as a user that

has this permission.


name and qid are missing.






EEWO0727E The following user does not have

"execute" privileges: user_name.



Operator response: Determine from the system

administrator whether the user can be granted

"execute" privileges. If not, rerun the job as a user that

has these privileges.



EEWO0729E The following user does not have any

access privileges: user_name.




administrator whether the user can be granted "access"

privileges. If not, you should rerun the job as a user

that has these privileges.

EEWO0730E No variants have been defined.



the data or exit.

Operator response: Define the missing variants and

continue.

See also: The User’s Guide for details about the how to

define variants.

EEWO0731E The ABAP program does not exist.



the data or exit.


administrator to determine the correct name of the

ABAP program. Modify the job definition and continue.

See also: The User’s Guide for details about how to

define ABAP programs.

EEWO0732E The ABAP program has no variants.



the data or exit.

Operator response: Define the missing variants and

continue.


define variants.

EEWO0733E The ABAP program is missing.

Explanation: You have tried to define variants but

have not yet identified an ABAP program.


the data or exit.

Operator response: Define the ABAP program

associated with the variants you were trying to enter

and continue.



EEWO0734E The ABAP program is not executable

Explanation: You have defined an ABAP program that

is not an executable file.


the data or exit.

Operator response: Choose a different ABAP program,

change the job definition, and continue.



EEWO0735E ABAP and external program set






EEWO0736E The selection has been cancelled.







startrow is not valid.






EEWO0738E The required interface is not supported

by the R/3 system.






EEWO0739E The version of the required interface is

not supported by the R/3 system.








EEWO0740E The user name is missing.



the data or exit.

Operator response: Add the missing user name to the

job definitions and continue.


"release" privileges: user_name.




administrator whether the user can be granted "release"

privileges. If not, rerun the job as a user that has these

privileges.


"abort" privileges: user_name.




administrator whether the user can be granted "abort"


privileges.


selection option is not valid.







select job name is missing.







select user name is missing.







"delete" privileges: user_name.




administrator whether the user can be granted "delete"


privileges.

EEWO0747E An internal error has occurred. A

running job could not be deleted. The

following identify the job:

Job name: job_name

Job ID: job_ID.








BP_JOB_COPY function could not copy

the following job:

Job name: job_name

Job ID: job_ID.


could not be copied.






joblog of the job cannot be deleted. The


Job name: job_name

Job ID: job_ID

Explanation: job_name and job_ID identify the job with

a joblog that could not be deleted.


Operator response: Check R/3 syslog.

EEWO0750E An internal error has occurred. An event

is missing a parameter.









does not exist.







could not be raised.







program could not commit the changes

in the database tables when calling the

following function module: module.





specified date and/or time is invalid.







specified server name is invalid







incorrect action was performed while

maintaining the status of interception

and parent-child functionality.







incorrect confirmation type was found

while confirming a job.







incorrect client was found while

retrieving intercepted jobs.






EEWO0759E The confirmation of a job has failed.





selection parameter is not valid.






EEWO0761E Parent-child functionality is not active.



Operator response: Activate parent-child functionality

as described in the User’s Guide. Rerun r3batch.

See also: The User’s Guide for instructions about how

to activate parent-child functions.

EEWO0762E Interception functionality is not active.


Operator response: Activate interception functionality

as described in the User’s Guide. Rerun r3batch.

See also: The User’s Guide for instructions about how

to activate interception functions.




incorrect counter value was found while

retrieving the list of reports.






EEWO0764E The specified printer is not recognized

by the R/3 system.






EEWO0765E An internal error occurred during the

registration of a child for the following

job:

Job name: job_name

Job ID: job_ID.

Explanation: job_name and job_ID identify the job for

which a child process could not be registered.






data for the following job could not be

read:

Job name: job_name

Job ID: job_ID.


data that could not be read.





EEWO0767E An internal error has occurred. The new

data for a job are not valid. The


Job name: job_name

Job ID: job_ID.


has new data that is not valid.






"modify" privileges: user_name.




administrator whether the user can be granted "modify"

privileges. If not, you should rerun the job as a user

that has these privileges.

EEWO0769E An internal error occurred while locking

a job in the R/3 database table. The


Job name: job_name

Job ID: job_ID.


could not be locked.






attempting to release the following job:

Job name: job_name

Job ID: job_ID.


could not be released.





EEWO0771E The target server for a job is not a valid

server. The following identify the job:

Job name: job_name

Job ID: job_ID.

Explanation: The target server indicated in the job

definition is not correct. It has either been incorrectly

typed or is not valid for the job.

job_name and job_ID identify the job that does not have

a valid server.

System action: The program waits for you to change

the job definitions and continue or to exit.


administrator to obtain the correct name of the target

server for this job. Change the job definition

accordingly and continue.



EEWO0772E An internal error has occurred. The start

date for a job is not valid. The


Job name: job_name

Job ID: job_ID.


has a non-valid start date.






following job can no longer be

modified:

Job name: job_name

Job ID: job_ID.


could not be modified.


Operator response: Retry the operation (the error

might be transient). If it persists, contact the SAP

system administrator to determine if the status of the

indicated job has been changed such that it is no longer

modifiable. If not, this is an internal error; contact IBM



problem has been found with the print

or archive mask, or both, while

modifying an ABAP step of the

following job:

Job name: job_name

Job ID: job_ID.


an ABAP step that has a problem with the print or

archive mask, or both.






that needs to be added to a job has the

wrong step type. The following identify

the job:

Job name: job_name

Job ID: job_ID.


has the wrong step type.






program could not retrieve the print and

archive parameters while adding a step

to the following job:

Job name: job_name

Job ID: job_ID.


which print and archive parameters could not be

retrieved.


Operator response: Check that all network

connections are working and retry the operation (the

error might be transient). If the problem persists, this is

an internal error; contact IBM Software Support for

assistance.


program could not retrieve information

about the following job:

Job name: job_name

Job ID: job_ID.


which information could not be retrieved.






assistance.


program could not modify the following

job:

Job name: job_name

Job ID: job_ID.


could not be modified.






assistance.


program could not modify the

worktable for the following job:

Job name: job_name

Job ID: job_ID.




which the worktable could not be modified.






assistance.


program could not read the worktable

for the following job:

Job name: job_name

Job ID: job_ID.


which the worktable could not be read.






assistance.


program could not modify the step for

the following job because no step

information has been provided:

Job name: job_name

Job ID: job_ID.


which the step information is not available.






assistance.

EEWO0782E The program has found an inconsistency

in the data concerning the parent-child

relationship for the following job:

Job name: job_name

Job ID: job_ID.


which the parent-child relationship data is not

consistent.






program has found incorrect selection

options.







program has found that the following

job does not have an expected step:

Job name: job_name

Job ID: job_ID.


which an expected step is missing.





EEWO0785E The variant already exists.







following user is not authorized to

perform the requested action: user_name.







report or variant is not valid.









variant name is not valid.







action has not been performed.







variant selections do not match.







variant has not been supplied.







report does not have selection screens.







report definition could not be loaded.







variant could not be locked.







variant could not be deleted.







variant variable maintenance parameters

are not valid.







table has no fields.







table is not active.







table is locked.









values for the requested field could not

be read.







function module J_1O1_DATETIME has

failed. The expression could not be

evaluated.







result buffer for variant placeholders is

too small.






EEWO0803E An internal syntax error has occurred in

the expression.


System action: R3batch waits for you to input data or

exit.

Operator response: Check the syntax of the date

expression in the job definition. If you find an error,

correct it and continue. If you do not find an error in

the expression, this is an internal error. Retry the



See also: The User’s Guide for details about the syntax

of the date expression.


last run time feature is not yet

supported.







calendar placeholder feature is not yet

supported.






EEWO0806E An internal syntax error has occurred:

the date expression is not terminated



exit.










the date expression contains no data.



exit.










the arithmetic expression is not

terminated.



exit.

Operator response: Check the syntax of the arithmetic







of the arithmetic expression.




the arithmetic expression contains no

data.



exit.









EEWO0810E An internal syntax error has occurred in

the arithmetic expression.



exit.










internal buffer is too small for the

arithmetic expression.







of the following InfoPackage has not

started: InfoPackage_name.

Explanation: InfoPackage_name identifies the

InfoPackage associated with this job or step.





EEWO0821E An internal error has occurred. No

scheduling data can be found for the

following InfoPackage: InfoPackage_name.







of the following InfoPackage does not

exist: InfoPackage_name.







table does not contain the requested

field.







variant has no description in the

requested language.






EEWO0825E An internal error has occurred. External

command steps are not supported for

versions of BC-XBP less than 2.0.








EEWO0826E The extended agent could not delete a

record from the interception criteria

table on the target R/3 system.

Explanation: The extended agent tried to delete an

interception criteria record on the R/3 system and the

remote operation failed.

System action: The operation is not performed, the

agent continues.


problem persists, contact your R/3 system

administrator.

EEWO0827E The value set for the

bdc_job_status_failed option is not

valid.

Explanation: The value set for the

bdc_job_status_failed option is not valid. The only

allowed values are: all, ignore, or an integer greater

than 0.

System action: The operation is not performed.

Operator response: Set a correct value for the option

and retry the operation.

EEWO0901W The following product could not be

registered for SIGTERM handling:

"product_name". SIGTERMs will be

ignored.


System action: R3batch continues but SIGTERMs are

ignored.

Operator response: If you require SIGTERM handling

for the correct processing of this job, stop the job, ask

the system administrator to allow SIGTERM handling

for this product, and rerun r3batch.

EEWO0902W The program cannot check the status of

the job; but will try again later.



Operator response: If it is important to know the

status of the job, look at the syslog to attempt to

identify what is preventing the status from being

obtained. For example, there might be a network

problem restricting the communication with the job.

EEWO0903W The job has been cancelled by the

Tivoli Workload Scheduler operator; see

the R/3 joblog for details.


System action: R3batch continues, but the job has

been cancelled.

Operator response: Check the R/3 joblog for more

details. Check with the Tivoli Workload Scheduler

operator the reasons for the job cancellation and decide

if you need to take any further action.

EEWO0904W The program could not copy the joblog

to stdout.


System action: R3batch continues. The problem with

copying the joblog does not impact how the job is

performed.

Operator response: If you need to consult the joblog,

do so on the R/3 system instead of locally.

EEWO0908W An internal error has occurred. The

program has found the following

incorrectly formed BDCWAIT keyword:

BDCWAIT_keyword.


System action: R3batch continues, but the BDCWAIT

is ignored.

Operator response: If the BDCWAIT is essential to the

successful performance of the job, stop the job. Retry

the operation (the error might be transient). If the


assistance.


following BDCWAIT keyword does not

have the correct syntax:

BDCWAIT_keyword.



is ignored.





assistance.

EEWO0910W An internal error has occurred. No

BDC sessions were found that matched

the following session name:

"session_name". The BDCWAIT will be

ignored.



is ignored.




EEWO0826E • EEWO0910W


1111

1111

1

11


assistance.

EEWO0911W An internal error has occurred. No

BDC sessions were found that matched

the following qid: "qid". The BDCWAIT

will be ignored.



is ignored.





assistance.


BDC session found previously can no

longer be found in the BDC status table.

The wait is terminated for the following

session: "session_name" and "queue_id".

Explanation: The program creates an internal table of

BDC sessions to maintain the status of each session. A

session that had previously been found and loaded into

the table can no longer be found.


is ended.





assistance.

EEWO0913W The following trace level in the job

definition is not valid: "trace_level". The

default value of 3 (DEBUG_MAX) is

used instead.

Explanation: The -tracelvl option in the job definition

has a value that is not valid.

System action: R3batch continues, using the default

trace level: DEBUG_MAX.

Operator response: Correct the value supplied in the

job definition for the -tracelvl option to one of the

values indicated in the User’s Guide.


-tracelvl option settings in the job definition.

EEWO0914W An internal error has occurred. Either

the joblog or the job protocol for the

following job does not exist:

Job name: job_name

Job ID: job_ID.


which the job protocol does not exist.

System action: R3batch continues, but log information

is not available.

Operator response: If you need to have log

information for the successful running of this job, stop

the job and contact the SAP system administrator to

determine why the joblog or job protocol does not

exist. When the problem has been resolved rerun

r3batch. If the problem persists, contact IBM Software


EEWO0915W An internal error has occurred. Either

the joblog or the job protocol for the

following job is empty:

Job name: job_name

Job ID: job_ID.


which the joblog is empty.


is not available.




determine why the joblog or job protocol is empty.

When the problem has been resolved rerun r3batch. If

the problem persists, contact IBM Software Support for

assistance.


step has no spool list



is not available.




determine why the step has no spool list. When the

problem has been resolved rerun r3batch.


spool ID is not valid



is not available.




determine why the spool ID is not valid. When the

problem has been resolved rerun r3batch. If the


assistance.

EEWO0911W • EEWO0917W


EEWO0918W The report list selection is finished

Explanation: The program is reading the report list

from the SAP system. Depending on circumstances, this

message might indicate that the process has completed

successfully, or that the selection has terminated

unexpectedly, with an internal error.


Operator response: Check that the reports received

from the SAP system are what you are expecting. If

they are not, rerun r3batch (the problem might be

transient). If the problem persists, contact IBM Software


EEWO0919W There are no background processing

resources active in the R/3 system.


System action: R3batch continues, but the job cannot

be run.


administrator to activate background processing

resources in the R/3 system.

EEWO0920W An internal error occurred. The

spoollist of the following job cannot be

read:

Job name: job_name

Job ID: job_ID.


which the spoollist could not be read.


is not available.




determine why the spool list cannot be read. When the

problem has been resolved rerun r3batch.


program requires the "-flag type=exec"

parameter to be specified for dynamic

job creation.

Explanation: This is an internal error caused by one

module of r3batch not supplying the indicated

parameter when calling another module.


created.

Operator response: Contact IBM Software Support for

assistance.

EEWO0930W The following language is not valid:

"language". The following default

language is used: "default_language".



Operator response: If you do not want the job to

continue in the indicated default language, stop the job.

To correct the language selection, edit the job options

and change the twsxa_lang or twsmeth_lang parameter

values to a valid value as described in the User’s Guide.

Then rerun r3batch.

See also: The User’s Guide for more information about

the language options.

EEWO0950W The RFC user is already logged on



Operator response: You might choose to warn the

SAP system administrator that a job for this RFC user

has been submitted, but that this user is already logged

on.

EEWO0960W No calendar data for the SAP Factory

Calendar ID and year range defined in

the input can be found in the SAP R/3

system.

Explanation: The SAP factory calendar ID and year

range specified with the r3batch "RSC" task could not

find any data to export.

System action: R3batch continues, but no output is

provided.

Operator response: Change the SAP Factory Calendar

ID, or year range, or both, and rerun the command.

EEWO0961W The external dependency cannot be

committed because the SAP event name:

"event_name" and event parameter:

"event_parameter" which is the subject of

the dependency has not been found on

the SAP system.

Explanation: You have tried to commit an external

dependency on the SAP event name and parameter

indicated in the message, but the event could not be

found on the SAP system. Either the SAP event is

incorrectly defined in Tivoli Workload Scheduler, or it

has not been created on the SAP system.


Operator response: Check if the SAP event and

parameter have been correctly defined in Tivoli

Workload Scheduler and change them, it they have not.

Check whether the SAP event exists on the SAP

system. If the event does not exist, and your



dependency is defined correctly, this message is for

information only.

EEWO0970W The SAP component: sap_comp does not

have the correct SAP support package

level installed. For details, see the SAP

Note: sap_note.

Explanation: R3batch tries to perform an SAP R/3

function, but the backend system does not have the

correct SAP support package level installed.


Operator response: Check the SAP system and follow

the instructions in the SAP Note.

EEWO0997W An internal error occurred while trying

to obtain the semaphore. The following

RFC function module will not be

synchronized: function_module.

Explanation: The semaphore allows the RFC function

modules to synchronize their use of system resources.

Without the semaphore, a module might time-out,

waiting for a resource to become available.

function_module is the RFC function module that cannot

obtain a semaphore.


Operator response: If the use of the semaphore is

important for the job being run, stop the job. Retry the


persists, check in the log and with the SAP system

administrator to try and determine why the semaphore

could not be obtained. If this is not possible to

determine, there is an internal error; contact IBM


EEWO0998W An internal error occurred while trying

to open the semaphore. The following

RFC function module will not be

synchronized: function_module.

Explanation: The semaphore allows the RFC function

modules to synchronize their use of system resources.

Without the semaphore, a module might time-out,

waiting for a resource to become available.

function_module is the RFC function module that cannot

open its semaphore.


Operator response: If the use of the semaphore is

important for the job being run, stop the job. Retry the


persists, check in the log and with the SAP system

administrator to try and determine why the semaphore

could not be obtained. If this is not possible to

determine, there is an internal error; contact IBM


EEWO1005W An error occurred while retrieving the

spool list for a step:


System action: R3batch continues, but return code

mapping of this job cannot be performed.

Operator response: If return code mapping is crucial

to the job, stop it, and contact the SAP system

administrator to determine why the spool list could not

be retrieved. When the problem has been resolved

rerun r3batch.

EEWO1034E An internal error has occurred. Conman

could not be run to submit the

intercepted SAP job:






EEWO1063W An error occurred while adding the

information about the submitted process

chain to the common serialization file

file_name. The process chain cannot be

restarted.


System action: R3batch continues, but the process

chain is not restarted.



EEWO1064W An error occurred while opening the

common serialization file file_name. The

process chain cannot be restarted.






EEWO1065W The environment variable env_var is

not set. The process chain cannot be

restarted.








1111

111

1

11

1 1 1 1 1

1

1 1

1 1

1 1 1

1

1 1

1 1

1 1 1

1

1 1

1 1

EEWO1066W The file file_name cannot be locked. It

will not be updated. The process chain

is not restarted.






EEWO1067W An error occurred while updating the

information about the submitted process

chain in the common serialization file

file_name. The process chain cannot be

restarted.






EEWO1069E The common serialization file does not

contain any information about the

process chain identified by value.






EEWO1070E The specified process ID process_id is not

valid. No process in the process chain

will be restarted.




Operator response: Specify a valid process ID and

retry the operation.

EEWO1066W • EEWO1070E


111

1

11

11

11111

1

11

11

1111

1

11

11

1111

1

11

11

Oracle access method messages - P

This section lists error and warning messages that might be issued by the Oracle

E-Business Suite access method processes.

EEWP0046E An error has occurred while launching

the back-end processes.


System action: The agent stops.

Operator response: Check the log for associated

messages. Try to identify and fix the problem, and

restart the agent. If the problem persists, contact IBM


EEWP0049I The Tivoli Workload Scheduler for

Oracle extended agent has terminated.

The return code is return_code


System action: The extended agent stops.

Operator response: If the return code is 0, the agent

has completed all its activities successfully.

If the return code is nonzero, look in the log for

preceding messages that give more information. Fix the

problem and restart the agent. If the problem persists,

contact IBM Software Support for assistance.

EEWP0050E An error has occurred in the Oracle

application.

Oracle messages can be found in the

Tivoli Workload Scheduler log. Some

messages might also be found in the

Oracle log file.


System action: The extended agent stops.

Operator response: Check in the Tivoli Workload

Scheduler log and in the Oracle log file named

sqlnet.log for associated messages. You might need to

contact the Oracle application administrator. Fix the

problem and restart the agent.

EEWP0101W back-end_program_name - You are using an

unencrypted password.

Explanation: The indicated back-end program has

found an unencrypted password in the options file.

This might be a violation of the security rules at your

workplace.

System action: The program continues.

Operator response: If you intended to leave the

password unencrypted, take no action.

If you do not want to use unencrypted passwords, stop

the agent, use the enigma utility to encrypt the

password, copy and paste the encrypted password into

the options file, save the options file, and retry the

operation.

EEWPD0410E MCMTJ - An error occurred while the

agent was stopping the Oracle job.

Explanation: An error occurred while the MCMTJ

back-end process was trying to stop the Oracle job.

System action: The agent stops.

Operator response: You might want to ask the Oracle

administrator to stop the Oracle job manually. Check in

the logs for associated messages that might explain

why the stop did not work. Fix any problems. If the

Oracle job has not yet been stopped, retry the

operation. If the problem persists, contact IBM Software


EEWP0046E • EEWPD0410E


PeopleSoft access method messages - HTWGT

This section lists error and warning messages that might be issued by thePeopleSoft

access method processes.

These messages are from Tivoli Workload Scheduler for Visualized Data Centers,

which has a product code of HTW. The subcomponent code is GT.

Note: The PeopleSoft access method also issues messages that are part of Tivoli

Workload Scheduler for Applications . see “PeopleSoft access method

messages - N” on page 276.

HTWGT0001E An internal error has occurred. The

program cannot initialize the option

source class "option_source_class" required

to read the global or local options file.


System action: The program cannot proceed.



assistance.


program cannot find the option source

class "option_source_class" required to

read the global or local options file.





assistance.

HTWGT0003W The value of the specified option

"option" is not valid.


System action: The program proceeds. The default

value for the computer where the access method is

running is used.

Operator response: If the default value is not correct,

cancel the job and resubmit it, supplying a valid value

for the option.

See also: The User’s Guide for a description of the

valid values for the option.

HTWGT0005E The program cannot read the file

"file".




v The file exists and the name of the file is correct.

v You have the correct permissions to access the file.

v The file is not corrupt.

When you have fixed the problem, retry the operation.

HTWGT0006E The job definition task string has not

been specified.



Operator response: Resubmit the job, specifying the

job definition task string.

See also: The User’s Guide for the syntax of the job

definition.

HTWGT0007W The specified option "option" has

been supplied without the required

value.


System action: The program proceeds, using the

default value.



for the option.



HTWGT0008W The specified option "option" has

been supplied more than once, with

different values.

Explanation: This message occurs if an option has

been supplied in more than one of the following:

v Job definition

v Local options

v Global options

System action: The program proceeds, using the value

according to the following hierarchy:

1. Job Definition

2. Local options

3. Global options


HTWGT0001E • HTWGT0008W



for the option.



HTWGT0009E The file "file" does not exist.



Operator response: Check whether the file has been

deleted, moved, or renamed. If the file is the local or

global options file, re-create, move, or rename it to the

correct name.

See also: The User’s Guide for details of the path and

name of the options files.

HTWGT0010E The file "file" cannot be read.



Operator response: Check whether the file has been

corrupted by attempting to read it. Ensure that no

process has locked it or is writing to it. Resolve the

problem and retry the operation.

HTWGT0011E An I/O error occurred when reading

from file "file".




v The file exists and the name of the file is correct.

v You have the correct permissions to access the file.

v The file is not corrupt.

v That no process has locked it or is writing to it.

Resolve the problem and retry the operation.

HTWGT0012E The program is trying to open the file

called "name" but the object with that

name is not a file.





assistance.


program cannot initialize the class

"class".





assistance.


program is not authorized to initialize

the class "class".





assistance.


program cannot find the class "class".





assistance.

HTWGT0016W A non-valid option line has been

detected in the options file "options_file".

The line "non-valid_option_line" is

ignored.


System action: The program proceeds, ignoring the

non-valid line and the option it contains.

Operator response: If the job needs the option in the

ignored line, cancel the job, edit the option file,

supplying a valid option line, and resubmit the

command.


program cannot open the logger class

"class".





assistance.

HTWGT0018E The task "task" you specified cannot

be run.

Explanation: This agent only supports job

submissions. You have tried to run it to perform a

different task, which is not allowed.


Operator response: Either rerun the program to

HTWGT0009E • HTWGT0018E


submit a job, or choose a different agent.


program cannot find the Tivoli

Workload Scheduler root directory

"install_directory".





assistance.


Tivoli Workload Scheduler root

directory "install_directory" you specified

is not a directory.





assistance.


program cannot read the Tivoli

Workload Scheduler root directory

"install_directory".





assistance.

HTWGT0022E An error was encountered while

initializing the options. The job will be

terminated.





assistance.

HTWGT0023W The value "option_value" you

specified for the option "option" is not

valid.



Operator response: Change the value for the option

and retry the operation.



HTWGT0019E • HTWGT0023W


Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this publication

in other countries. Consult your local IBM representative for information on the

products and services currently available in your area. Any reference to an IBM

product, program, or service is not intended to state or imply that only that IBM

product, program, or service may be used. Any functionally equivalent product,

program, or service that does not infringe any IBM intellectual property right may

be used instead. However, it is the user’s responsibility to evaluate and verify the

operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter

described in this publication. The furnishing of this publication does not give you

any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM

Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other

country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER

EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS

FOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certain

transactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be

incorporated in new editions of the publication. IBM may make improvements

and/or changes in the product(s) and/or the program(s) described in this

publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for

convenience only and do not in any manner serve as an endorsement of those Web

sites. The materials at those Web sites are not part of the materials for this IBM

product and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way it

believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose

of enabling: (i) the exchange of information between independently created

programs and other programs (including this one) and (ii) the mutual use of the

information which has been exchanged, should contact:

IBM Corporation

2Z4A/101

11400 Burnet Road

Austin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases payment of a fee.

The licensed program described in this publication and all licensed material

available for it are provided by IBM under terms of the IBM Customer Agreement,

IBM International Program License Agreement or any equivalent agreement

between us.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.

IBM has not tested those products and cannot confirm the accuracy of

performance, compatibility or any other claims related to non-IBM products.

Questions on the capabilities of non-IBM products should be addressed to the

suppliers of those products.

This information contains examples of data and reports used in daily business

operations. To illustrate them as completely as possible, the examples include the

names of individuals, companies, brands, and products. All of these names are

fictitious and any similarity to the names and addresses used by an actual business

enterprise is entirely coincidental.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may

vary significantly. Some measurements may have been made on development-level

systems and there is no guarantee that these measurements will be the same on

generally available systems. Furthermore, some measurement may have been

estimated through extrapolation. Actual results may vary. Users of this document

should verify the applicable data for their specific environment.

If you are viewing this information in softcopy form, the photographs and color

illustrations might not appear.

Notices and information

The IBM license agreement and any applicable notices on the web download page

for this product refers You to this file for details concerning terms and conditions

applicable to software code identified as excluded components in the License

Information document and included in IBM Tivoli Workload Scheduler for

Applications 8.4.0 (the ″Program″).

Notwithstanding the terms and conditions of any other agreement you may have

with IBM or any of its related or affiliated entities (collectively ″IBM″), the third

party software code identified below are ″Excluded Components″ and are subject


to the terms and conditions of the License Information document accompanying

the Program and not the license terms that may be contained in the notices below.

The notices are provided for informational purposes.

The Program includes the following Excluded Components:

v libmsg

v Jakarta ORO

v ISMP Installer

v HSQLDB

v Quick

v Infozip

Libmsg

For the code entitled Libmsg

Permission to use, copy, modify, and distribute this software and its documentation

for any purpose and without fee is hereby granted, provided that the above

copyright notice appear in all copies and that both that copyright notice and this

permission notice appear in supporting documentation, and that Alfalfa’s name not

be used in advertising or publicity pertaining to distribution of the software

without specific, written prior permission.

ALPHALPHA DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS

SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY

AND FITNESS, IN NO EVENT SHALL ALPHALPHA BE LIABLE FOR ANY

SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER

TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE

OR PERFORMANCE OF THIS SOFTWARE.

Apache Jakarta ORO

For the code entitled Jakarta ORO

The Apache Software License, Version 1.1

Copyright (c) 2000-2002 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification,

are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list

of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this

list of conditions and the following disclaimer in the documentation and/or

other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must

include the following acknowledgment: ″This product includes software

developed by the Apache Software Foundation (http://www.apache.org/).″

Alternately, this acknowledgment may appear in the software itself, if and

wherever such third-party acknowledgments normally appear.

Notices 319

4. The names ″Apache″ and ″Apache Software Foundation″, ″Jakarta-Oro″ must

not be used to endorse or promote products derived from this software without

prior written permission. For written permission, please contact

[email protected].

5. Products derived from this software may not be called ″Apache″ or

″Jakarta-Oro″, nor may ″Apache″ or ″Jakarta-Oro″ appear in their name,

without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED ``AS IS’’ AND ANY EXPRESSED OR IMPLIED

WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE

FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,

INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR

BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF

THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on

behalf of the Apache Software Foundation. For more information on the Apache

Software Foundation, please see http://www.apache.org/.

Portions of this software are based upon software originally written by Daniel F.

Savarese. We appreciate his contributions.

ISMP Installer (InstallShield 10.50x)

For the code entitled ISMP Installer (InstallShield 10.50x)

The Program includes the following Excluded Components:

v Quick V1.0.1

v HSQLDB V1.7.1

v InfoZip Unzip stub file V5.40, V5.41,V5.42 & V5.5

JXML CODE

For the code entitled Quick

JXML CODE. The Program is accompanied by the following JXML software:

v Quick V1.0.1

IBM is required to provide you, as the recipient of such software, with a copy of

the following license from JXML:

Copyright (c) 1998, 1999, JXML, Inc.

All rights reserved.



v Redistributions of source code must retain the above copyright notice, this list of

conditions and the following disclaimer.


v Redistributions in binary form must reproduce the above copyright notice, this

list of conditions and the following disclaimer in the documentation and/or

other materials provided with the distribution.

All product materials mentioning features or use of this software must display the

following acknowledgement:

v This product includes software developed by JXML, Inc. and its contributors:

http://www.jxml.com/mdsax/contributers.html

Neither name of JXML nor the names of its contributors may be used to endorse or

promote products derived from this software without specific prior written

permission.

THIS SOFTWARE IS PROVIDED BY JXML, INC. AND CONTRIBUTORS ″AS IS″

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND

FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT

SHALL JXML OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,

INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE

GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,

WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF

THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH

DAMAGE.

InfoZip CODE

For the code entitled InfoZip

InfoZip CODE. The Program is accompanied by the following InfoZip software:

v One or more of: InfoZip Unzipsfx stub file V5.40, V5.41, V5.42 & V5.5


the following license from InfoZip:

v This is version 2000-Apr-09 of the Info-ZIP copyright and license.

The definitive version of this document should be available at

ftp://ftp.info-zip.org/pub/infozip/license.html indefinitely.

Copyright (c) 1990-2000 Info-ZIP. All rights reserved.

For the purposes of this copyright and license, ″Info-ZIP″ is defined as the

following set of individuals:

v Mark Adler, John Bush, Karl Davis, Harald Denker, Jean-Michel Dubois,

Jean-loup Gailly, Hunter Goatley, Ian Gorman, Chris Herborth, Dirk Haase, Greg

Hartwig, Robert Heath, Jonathan Hudson, Paul Kienitz, David Kirschbaum,

Johnny Lee, Onno van der Linden, Igor Mandrichenko, Steve P. Miller, Sergio

Monesi, Keith Owens, George Petrov, Greg Roelofs, Kai Uwe Rommel, Steve

Salisbury, Dave Smith, Christian Spieler, Antoine Verheijen, Paul von Behren,

Rich Wales, Mike White

Notices 321

This software is provided ″as is,″ without warranty of any kind, express or

implied. In no event shall Info-ZIP or its contributors be held liable for any direct,

indirect, incidental, special or consequential damages arising out of the use of or

inability to use this software.

Permission is granted to anyone to use this software for any purpose, including

commercial applications, and to alter it and redistribute it freely, subject to the

following restrictions:

1. Redistributions of source code must retain the above copyright notice,

definition, disclaimer, and this list of conditions.

2. Redistributions in binary form must reproduce the above copyright notice,

definition, disclaimer, and this list of conditions in documentation and/or other

materials provided with the distribution.

3. Altered versions--including, but not limited to, ports to new operating systems,

existing ports with new graphical interfaces, and dynamic, shared, or static

library versions--must be plainly marked as such and must not be

misrepresented as being the original source. Such altered versions also must not

be misrepresented as being Info-ZIP releases--including, but not limited to,

labeling of the altered versions with the names ″Info-ZIP″ (or any variation

thereof, including, but not limited to, different capitalizations), ″Pocket UnZip,″

″WiZ″ or ″MacZip″ without the explicit permission of Info-ZIP. Such altered

versions are further prohibited from misrepresentative use of the Zip-Bugs or

Info-ZIP e-mail addresses or of the Info-ZIP URL(s).

4. Info-ZIP retains the right to use the names ″Info-ZIP,″ ″Zip,″ ″UnZip,″ ″WiZ,″

″Pocket UnZip,″ ″Pocket Zip,″ and ″MacZip″ for its own source and binary

releases.

HSQL Code

For the code entitled HSQLDB

HSQL CODE. The Program is accompanied by the following HSQL Development

Group software:

v HSQLDB V1.7.1


the following license from the HSQL Development Group:

Copyright (c) 2001-2002, The HSQL Development Group All rights reserved.



Redistributions of source code must retain the above copyright notice, this list of

conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list

of conditions and the following disclaimer in the documentation and/or other

materials provided with the distribution.

Neither the name of the HSQL Development Group nor the names of its

contributors may be used to endorse or promote products derived from this

software without specific prior written permission.


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND

CONTRIBUTORS ″AS IS″ AND ANY EXPRESS OR IMPLIED WARRANTIES,

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP,

HSQLDB.ORG, OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,

INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE

GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,

WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF

THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH

DAMAGE.

HP-UX Runtime Environment, for the Java(tm) 2 Platform

TERMS FOR SEPARATELY LICENSED CODE

This Program includes HP Runtime Environment for J2SE HP-UX 11i platform

software as a third party component, which is licensed to you under the terms of

the following HP-UX license agreement and not those of this Agreement

HP-UX Runtime Environment license text

HP-UX Runtime Environment, for the Java(tm) 2 Platform

ATTENTION: USE OF THE SOFTWARE IS SUBJECT TO THE HP SOFTWARE

LICENSE TERMS AND SUPPLEMENTAL RESTRICTIONS SET FORTH BELOW,

THIRD PARTY SOFTWARE LICENSE TERMS FOUND IN THE

THIRDPARTYLICENSEREADME.TXT FILE AND THE WARRANTY DISCLAIMER

ATTACHED. IF YOU DO NOT ACCEPT THESE TERMS FULLY, YOU MAY NOT

INSTALL OR OTHERWISE USE THE SOFTWARE. NOTWITHSTANDING

ANYTHING TO THE CONTRARY IN THIS NOTICE, INSTALLING OR

OTHERWISE USING THE SOFTWARE INDICATES YOUR ACCEPTANCE OF

THESE LICENSE TERMS.

HP SOFTWARE LICENSE TERMS

The following terms govern your use of the Software unless you have a separate

written agreement with HP. HP has the right to change these terms and conditions

at any time, with or without notice.

License Grant

HP grants you a license to Use one copy of the Software. ″Use″ means storing,

loading, installing, executing or displaying the Software. You may not modify the

Software or disable any licensing or control features of the Software. If the

Software is licensed for ″concurrent use″, you may not allow more than the

maximum number of authorized users to Use the Software concurrently.

Ownership

Notices 323

The Software is owned and copyrighted by HP or its third party suppliers. Your

license confers no title or ownership in the Software and is not a sale of any rights

in the Software. HP’s third party suppliers may protect their rights in the event of

any violation of these License Terms.

Third Party Code

Some third-party code embedded or bundled with the Software is licensed to you

under different terms and conditions as set forth in the

THIRDPARTYLICENSEREADME.txt file. In addition to any terms and conditions

of any third party license identified in the THIRDPARTYLICENSEREADME.txt file,

the disclaimer of warranty and limitation of liability provisions in this license shall

apply to all code distributed as part of or bundled with the Software.

Source Code

Software may contain source code that, unless expressly licensed for other

purposes, is provided solely for reference purposes pursuant to the terms of this

license. Source code may not be redistributed unless expressly provided for in

these License Terms.

Copies and Adaptations

You may only make copies or adaptations of the Software for archival purposes or

when copying or adaptation is an essential step in the authorized Use of the

Software. You must reproduce all copyright notices in the original Software on all

copies or adaptations. You may not copy the Software onto any bulletin board or

similar system.

No Disassembly or Decryption

You may not disassemble or decompile the Software unless HP’s prior written

consent is obtained. In some jurisdictions, HP’s consent may not be required for

disassembly or decompilation. Upon request, you will provide HP with reasonably

detailed information regarding any disassembly or decompilation. You may not

decrypt the Software unless decryption is a necessary part of the operation of the

Software.

Transfer

Your license will automatically terminate upon any transfer of the Software. Upon

transfer, you must deliver the Software, including any copies and related

documentation, to the transferee. The transferee must accept these License Terms

as a condition to the transfer.

Termination

HP may terminate your license upon notice for failure to comply with any of these

License Terms. Upon termination, you must immediately destroy the Software,

together with all copies, adaptations and merged portions in any form.

Export Requirements

You may not export or re-export the Software or any copy or adaptation in

violation of any applicable laws or regulations.


This software or any copy or adaptation may not be exported, reexported or

transferred to or within countries under U.S. economic embargo including the

following countries: Afghanistan (Taliban-controlled areas), Cuba, Iran, Iraq, Libya,

North Korea, Serbia, Sudan and Syria. This list is subject to change.

This software or any copy or adaptation may not be exported, reexported or

transferred to persons or entities listed on the U.S. Department of Commerce

Denied Parties List or on any U.S. Treasury Department Designated Nationals

exclusion list, or to any party directly or indirectly involved in the development or

production of nuclear, chemical, biological weapons or related missile technology

programs as specified in the U.S. Export Administration Regulations (15 CFR 730).

U.S. Government Contracts

If the Software is licensed for use in the performance of a U.S. government prime

contract or subcontract, you agree that, consistent with FAR 12.211 and 12.212,

commercial computer Software, computer Software documentation and technical

data for commercial items are licensed under HP’s standard commercial license.

SUPPLEMENTAL RESTRICTIONS

You acknowledge the Software is not designed or intended for use in on-line

control of aircraft, air traffic, aircraft navigation, or aircraft communications; or in

the design, construction, operation or maintenance of any nuclear facility. HP

disclaims any express or implied warranty of fitness for such uses.

ADDITIONAL SUPPLEMENTAL RESTRICTIONS FOR HP-UX RUNTIME

ENVIRONMENT, FOR THE JAVA(TM) 2 PLATFORM

v * License to Distribute HP-UX Runtime Environment, for the Java(tm) 2

Platform. You are granted a royalty-free right to reproduce and distribute the

HP-UX Runtime Environment, for Java provided that you distribute the HP-UX

Runtime Environment, for the Java 2 Platform complete and unmodified, only as

a part of, and for the sole purpose of running your Java compatible applet or

application (″Program″) into which the HP-UX Runtime Environment, for the

Java 2 Platform is incorporated.

v * Java Platform Interface. Licensee may not modify the Java Platform Interface

(″JPI″, identified as classes contained within the ″java″ package or any

subpackages of the ″java″ package), by creating additional classes within the JPI

or otherwise causing the addition to or modification of the classes in the JPI. In

the event that Licensee creates any Java-related API and distributes such API to

others for applet or application development, Licensee must promptly publish

broadly, an accurate specification for such API for free use by all developers of

Java-based software.

v * You may make the HP-UX Runtime Environment, for the Java 2 Platform

accessible to application programs developed by you provided that the

programs allow such access only through the Invocation Interface specified and

provided that you shall not expose or document other interfaces that permit

access to such HP-UX Runtime Environment, for the Java 2 Platform. You shall

not be restricted hereunder from exposing or documenting interfaces to software

components that use or access the HP-UX Runtime Environment, for the Java 2

Platform.

HP WARRANTY STATEMENT

DURATION OF LIMITED WARRANTY: 90 DAYS

Notices 325

HP warrants to you, the end customer, that HP hardware, accessories, and supplies

will be free from defects in materials and workmanship after the date of purchase

for the period specified above. If HP receives notice of such defects during the

warranty period, HP will, at its option, either repair or replace products which

prove to be defective. Replacement products may be either new or equivalent in

performance to new.

HP warrants to you that HP Software will not fail to execute its programming

instructions after the date of purchase, for the period specified above, due to

defects in materials and workmanship when properly installed and used. If HP

receives notice of such defects during the warranty period, HP will replace

Software which does not execute its programming instructions due to such defects.

HP does not warrant that the operation of HP products will be uninterrupted or

error free. If HP is unable, within a reasonable time, to repair or replace any

product to a condition warranted, you will be entitled to a refund of the purchase

price upon prompt return of the product. Alternatively, in the case of HP Software,

you will be entitled to a refund of the purchase price upon prompt delivery to HP

of written notice from you confirming destruction of the HP Software, together

with all copies, adaptations, and merged portions in any form.

HP products may contain remanufactured parts equivalent to new in performance

or may have been subject to incidental use.

Warranty does not apply to defects resulting from: (a) improper or inadequate

maintenance or calibration; (b) software, interfacing, parts or supplies not supplied

by HP, (c) unauthorized modification or misuse; (d) operation outside of the

published environmental specifications for the product, (e) improper site

preparation or maintenance, or (f) the presence of code from HP suppliers

embedded in or bundled with any HP product.

TO THE EXTENT ALLOWED BY LOCAL LAW, THE ABOVE WARRANTIES ARE

EXCLUSIVE AND NO OTHER WARRANTY OR CONDITION, WHETHER

WRITTEN OR ORAL, IS EXPRESSED OR IMPLIED AND HP SPECIFICALLY

DISCLAIMS ANY IMPLIED WARRANTIES OR CONDITIONS OF

MERCHANTABILITY, SATISFACTORY QUALITY, AND FITNESS FOR A

PARTICULAR PURPOSE. Some countries, states, or provinces do not allow

limitations on the duration of an implied warranty, so the above limitation or

exclusion may not apply to you. This warranty gives you specific legal rights and

you might also have other rights that vary from country to country, state to state,

or province to province.

TO THE EXTENT ALLOWED BY LOCAL LAW, THE REMEDIES IN THIS

WARRANTY STATEMENT ARE YOUR SOLE AND EXCLUSIVE REMEDIES.

EXCEPT AS INDICATED ABOVE, IN NO EVENT WILL HP OR ITS SUPPLIERS

BE LIABLE FOR LOSS OF DATA OR FOR DIRECT, SPECIAL, INCIDENTAL,

CONSEQUENTIAL (INCLUDING LOST PROFIT OR DATA), OR OTHER

DAMAGE, WHETHER BASED IN CONTRACT, TORT, OR OTHERWISE. Some

countries, states, or provinces do not allow the exclusion or limitation of incidental

or consequential damages, so the above limitation may not apply to you.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.

IBM has not tested those products and cannot confirm the accuracy of


performance, compatibility or any other claims related to non-IBM products.

Questions on the capabilities of non-IBM products should be addressed to the

suppliers of those products.

Trademarks

Java and all Java-based trademarks and logos are trademarks or

registered trademarks of Sun Microsystems, Inc. in the United States,

other countries, or both.

Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registered

trademarks or trademarks of Adobe Systems Incorporated in the United States,

other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or

both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of

Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other

countries.

Other company, product, and service names may be trademarks or service marks

of others.

Notices 327


Index

AABAP step definition

attribute 156

ABAP/4 modulesSAP R/3 importing 98

access methodadding with ISMP wizard 11

adding with twsappsinst 26

installing with silent installation 14

MCMAGENT options 63

PeopleSoft options 75

SAP 91

SAP common options 106

SAP global configuration options 103

SAP local configuration options 105

twsappsinst parameter 27

upgrading with ISMP wizard 33

z/OS options 221

accessibility xv

activatingjob interception 175

addingaccess method with ISMP wizard 11

access method with twsappsinst 26

IBM Tivoli Workload Scheduler for Applications with

twsappsinst 26

language pack with ISMP wizard 13

language pack with silent installation 17

language pack with twsappsinst 28

AI component codetwsappsinst installation messages 266

APARsIY97424 177, 178

IZ02886 63

IZ03505 103, 104, 105

IZ12321 249

APF authorizations, setting 211

application serverSAP R/3 112

application serversmultiple, PeopleSoft 77

application stateTivoli Workload Scheduler for z/OS 233

authorization profileSAP R/3 95

Transaction PFCG 96

Transaction SU02 96

authorizationsAPF, setting 211

RACF, setting 211

Bbalancing SAP R/3 workload using server groups 144

batch processing IDPeopleSoft 78

BDC waitR/3 173

BLOCKTIME, z/OS option 222

bm check status 231, 233

Business Information Warehouse supportSAP R/3 163

Business Warehouse componentsInfoPackage 163

process chain 163

SAP R/3 163

Business Warehouse InfoPackagedisplaying details 169

Business Warehouse InfoPackage and process chainmanaging 164

CCA-7 job

checking 231

launching 231

managing 231

state 231

task definition, z/OS 223

CA7INTERFACE, SYSTSIN variable 213

CA7NAME, SYSTSIN variable 213

CA7OPTIONS, SYSTSIN variable 213

CA7SPAN(9999), SYSTSIN variable 214

CA7SUBSYSTEM, SYSTSIN variable 214

CA7USER, SYSTSIN variable 214

CA7WAIT, SYSTSIN variable 214

CDs 8

CFUSER, z/OS option 222

CFUSER: Oracle option 63

changing password, RFC userSAP R/3 101

checkingCA-7 job 231

for files on z/OS 234

JES job 230

Tivoli Workload Scheduler for z/OS job 233

CHECKINTERVAL, PeopleSoft option 75

CHECKINTERVAL, z/OS option 222

codemessages 263

collecting job interception 175

commandSETPROG 211

setup.bin 11, 13

twsappsinst 27, 29, 35, 40

uninstaller.bin 38, 39, 40

vopted.sh 44

wremovsp 39

command linecommitting SAP event 187

defining extended agent job 57

defining extended agent workstation 50

monitoring SAP event 190

command twsappsinstexample to install language pack 30

example to install Tivoli Workload Scheduler for

Applications 28

example to uninstall version 8.4 41

example to upgrade to version 8.4 36

common options, SAP 106


compatibilitySAP 89

COMPLETIONCODE, SYSTSIN variable 215

component codeTivoli Workload Scheduler for Applications component

codes 264

composer programdefining extended agent job 57


configurationSAP R/3 204

configuration fileexample, R/3 249

configuration optionsOracle E-Business Suite 63

PeopleSoft 75

SAP, common 106

SAP, global 103

SAP, local 105

SAP, usage 111

z/OS 221

configuringSAP access method 103

SAP environment 95

SAP R/3 95

tracing utility 247

z/OS 221

z/OS gateway 210

connectingSAP 112

connection to SAP R/3troubleshooting 261

considerations about return code mapping 240

console security 213

control fileSAP R/3 98

conventions used in publications xv

correction and transport filesSAP R/3 98

CPUREC statementcreating 51

creatingCPUREC statement 51

DOMREC statement 51

event rule based on IDocs 196

event rule based on IDocs, business scenario 195

event rule based on SAP event 189

internetwork dependency based on SAP event 186, 188

job containing InfoPackage 164

job containing process chains 164

local options file 46

PeopleSoft job 83

RFC user, SAP R/3 95

SAP job 115

CUSTOM keyword, to filter SAP events 192

customization procedureSAP R/3 95

customizingproperties file 247, 248

Ddata file

SAP R/3 98

DEBUG, SYSTSIN variable 215

definingABAP step attribute 156

defining (continued)event rule based on IDocs 196


event rule based on SAP event 189

extended agent job 53

extended agent workstation 47

external command step attribute 159

external program step attribute 159

global options file 43


Oracle E-Business Suite job 67

PeopleSoft job 83

SAP event as internetwork dependency 186, 188

SAP job 115, 129

SAP job dynamically 149

SAP R/3 job 169

SAP variant 126

defining jobOracle E-Business Suite 67

SAP 129

SAP, dynamically 149

z/OS 222

deletingSAP job 144

SAP variant 126

dependencybased on SAP event, defining 186, 188

based on SAP event, limitation with XBP 2.0 185

committing SAP event by external request 187

mapping between definition and resolution, SAP 187

dependency on jobsz/OS 225

diagnostic informationz/OS job 235

displaying detailsBusiness Warehouse InfoPackage 169

Business Warehouse InfoPackage job 169

process chain job 142

SAP job 141

DOMREC statementcreating 51

downloading z/OS gateway fix pack files by FTP 218

dynamic job definition parameter descriptionSAP R/3 151

dynamic job definition syntaxABAP step definition attribute 156

external command step definition attribute 159

external program step definition attribute 159

SAP 150

dynamicallydefining SAP jobs 150

dynamically, defining SAP job 149

Eeducation

See Tivoli technical training

EEWTCP00z/OS program component 212

EEWTCP02z/OS program component 212

encrypting user password 66

PeopleSoft 77

SAP 111

end-to-end schedulingdefining extended agent job 57



enigma 66

enigma programencrypting user password 111

ENV: Oracle option 63

error messages, definition 264

event rulebased on IDocs 196

based on IDocs, business scenario 195

based on IDocs, matching criteria 196

definition 189

monitoring SAP event 190

SAP, defining 189

SAP, filtering events 192

SAP, prerequisite to define 190

exampledynamic SAP job definition 160

mcmagent.opts file 65

return code mapping 240, 242

to install the language pack using twsappsinst 30

to install the product using twsappsinst 28

to uninstall version 8.4 using twsappsinst 41

to upgrade to version 8.4 using twsappsinst 36

explanationmessage element 265

exporting SAP R/3 factory calendars 181

extended agent jobSAP 115

submitting 58

extended agent job defining withcommand line 57

end-to-end scheduling 57

Job Scheduling Console 53

extended agent workstation defining withend-to-end scheduling 51

extended agent workstation, defining withcommand line 50

ISPF 52


external command step definitionattribute 159

external program step definitionattribute 159

Ffeature

job interception, setting SAP R/3 176

featuresjob interception and parent-child, SAP R/3 175

job interception, activating SAP R/3 175

job interception, collecting SAP R/3 175

job interception, implementing SAP R/3 175

job interception, R/3 175

job interception, setting SAP R/3 176

Oracle E-Business Suite 61

parent-child R/3 180

PeopleSoft 73

return code mapping 239

SAP R/3 90

z/OS 207

fileconfiguration for R/3 249

language pack Software Package Blocks (.spb) 22

mcmagent.properties 247

mvsca7.properties 247

mvsjes.properties 247

mvsopc.properties 247

file (continued)product Software Package Blocks (.spb) 19

psagent.properties 247

r3batch.properties 247


Software Package Blocks (.spb) 22

TWS4APPS_installationname_accessmethod^8.4.log, ISMP

installation 11, 33, 38

TWS4APPS_installationname_accessmethod^8.4.log, silent

installation 14


uninstallation 40

TWS4APPS_installationname_accessmethod^8.4.log,

twsappsinst 35, 40

TWS4APPS_installationname_LANGS^8.4.log, ISMP

installation 13


uninstallation 38

TWS4APPS_installationname_LANGS^8.4.log, silent

installation 17


uninstallation 39

TWS4APPS_installationname_LANGS^8.4.log,

twsappsinst 40

tws4apps_ismp.log, ISMP installation 11, 33

tws4apps_ismp.log, silent installation 14

tws4apps_uninst_ismp.log, ISMP installation 38

tws4apps_uninst_ismp.log, silent uninstallation 40

tws4appslangs_uninst.log, ISMP uninstallation 38

tws4appslangs_uninst.log, silent uninstallation 39

tws4appslangs.log 17

tws4appslangs.log, ISMP installation 13

tws4appslangsilent.txt, silent installation 17

tws4appssilent.txt, silent installation 14

twsappsinst.log 35, 40

file namereturn code mapping 244

filtering SAP events in security file 192

fix pack files, z/OS gateway, downloading by FTP 218

FND_TOPDIR: Oracle option 63

formatmessages 263

FTPdownloading fix pack files, z/OS gateway installation 218

Ggateway

z/OS messages 270

global options filedefining 43

MCMAGENT.opts 43

modifying with Option Editor 44, 46

mvsca7.opts 43

mvsjes.opts 43

mvsopc.opts 43

name 43

psagent.opts 43

r3batch.opts 43

global options, SAP 103

glossary xv

GSUSER, z/OS option 222

Index 331

Hhelp

messages 265

HTWGT component codePeopleSoft access method 314

II component code

z/OS message 270

IBM Tivoli Configuration ManagerJava Runtime Environment (JRE) installing 24

language pack installing 25

Option Editor installing 25

PeopleSoft installing 25

SAP R/3 installing 24

IBM Tivoli Workload Scheduler for Applicationsaccess method, adding with twsappsinst 26

before installing 9

example to install using twsappsinst 28

example to uninstall version 8.4 using twsappsinst 41

example to upgrade to version 8.4 using twsappsinst 36

installation prerequisites 6

installation procedures 10

installing 10

installing with ISMP wizard 11

installing with launchpad 10

installing with silent installation 14

installing with Tivoli Configuration Manager 19

installing with Tivoli Software Distribution 19

installing with twsappsinst 26

language pack uninstalling with ISMP wizard 38

software prerequisites 6

uninstallation procedures 37

uninstalling 36

uninstalling language pack with silent uninstallation 39

uninstalling with ISMP wizard 38

uninstalling with silent installation 40

uninstalling with Tivoli Configuration Manager 39

uninstalling with twsappsinst 40

upgrading 33

upgrading with ISMP wizard 33

upgrading with twsappsinst 35

IDocdefining event rule 196

defining event rule, business scenario 195

defining event rule, matching criteria 196

IEFU84 exit 212

implementingjob interception 175

InfoPackagemanaging 164

user authorization 164

InfoPackage schedule optionsSAP R/3 164

informational messages, definition 264

inheritance r3batchdefinition 44

inst_dirtwsappsinst parameter 27, 29, 35, 40

install IBM Tivoli Workload Scheduler for Applicationstwsappsinst parameter 27

install language packtwsappsinst parameter 29

installation 217

CDs 8

installation (continued)twsappsinst message 266

installation CDSTivoli Workload Scheduler for Applications CD 1 8

Tivoli Workload Scheduler for Applications CD 2 8



installation log fileTivoli Configuration Manager 24, 25


installation 11, 33


installation 14


twsappsinst 35


installation 13


installation 17





twsappsinst.log 35

installation overviewz/OS 208

installation procedures 10

installation response filetws4appslangsilent.txt, silent installation 17


installingaccess method with silent installation 11

before 9

IBM Tivoli Workload Scheduler for Applications 10

IBM Tivoli Workload Scheduler for Applications with ISMP

wizard 11


launchpad 10

IBM Tivoli Workload Scheduler for Applications with silent

installation 14


Tivoli Configuration Manager 19


Tivoli Software Distribution 19


twsappsinst 26

Java Runtime Environment (JRE) with Tivoli Configuration

Manager 24


language pack with silent installation 17

language pack with Tivoli Configuration Manager 25

language pack with twsappsinst 28

Option Editor with Tivoli Configuration Manager 25

PeopleSoft with Tivoli Configuration Manager 25

prerequisites 6

procedures 10

SAP R/3 with Tivoli Configuration Manager 24

z/OS gateway 208

installing ABAP modulesSAP R/3 95

intercepted jobreturn code mapping 245

interception criteriasetting, SAP R/3 feature 176

interfacesoftware 62


INTERLINKSUBSYSTEM, SYSTSIN variableSYSTSIN variable

INTERLINKSUBSYSTEM 215

internetwork dependencybased on SAP event, defining 186, 188



based on SAP R/3 event, prerequisites 185

committing SAP event by external request 187

mapping between definition and resolution, SAP 187

placeholder SAP job 185

introductionOracle E-Business Suite 61

PeopleSoft 73

Tivoli Workload Scheduler for Applications for SAP 89

z/OS 207

ISMP wizardadding a language 13

adding an access method 11

installing IBM Tivoli Workload Scheduler for

Applications 11

installing language pack 13

installing with 11

uninstalling IBM Tivoli Workload Scheduler for

Applications 38

uninstalling language pack 38

upgrading IBM Tivoli Workload Scheduler for

Applications 33

upgrading with 33

ISPFdefining extended agent workstation 52

ITWS_PSXA projectPeopleSoft 78

JJava Runtime Environment (JRE)


JCL to unload the tapez/OS gateway installation 209

JES jobchecking 230

launching 229

managing 229

monitoring 230

state 229


JES operation overview 229, 230

JESCMDCHR, SYSTSIN variable 215

JESINTERFACE, SYSTSIN variable 215

jobassigning a server group 144

Oracle E-Business Suite job states 69

PeopleSoft 83

SAP job state 145

submitting for extended agent 58

job definitionPeopleSoft 83

SAP 129

SAP, dynamically 149

job definition parameter descriptionSAP R/3 dynamic 151

job interceptionactivating, SAP R/3 feature 175

collecting, SAP R/3 feature 175

implementing, SAP R/3 feature 175

SAP R/3 feature 175

job interception (continued)setting placeholders in template file 179

setting, SAP R/3 feature 176

Job Scheduling Consoleaccessibility xv

defining extended agent job 53


job stateOracle E-Business Suite 69

SAP 145

job status mappingPeopleSoft 85

job Tivoli Workload Schedulercreating job containing InfoPackage 164

creating job containing process chain 164

job trackingPeopleSoft 74

jobs dynamic definitionSAP 150

Kkilling SAP job 147

Llang

twsappsinst parameter 27, 29, 35, 40

languageadding with twsappsinst 28

twsappsinst parameter 29

language packaccess method adding with twsappsinst 28

adding with ISMP wizard 13

example to install using twsappsinst 30

installing with ISMP wizard 13


installing with twsappsinst 28

response file 17

silent installation 17

silent installation options 18

silent uninstallation 39


launchingCA-7 job 231

JES job 229


launchpadinstalling with 10

LJUSER, PeopleSoft option 75

LJUSER, z/OS option 222

local options filecreating with Option Editor 46

defining 43

modifying with Option Editor 44, 46

name 43

local options, SAP R/3 105

log fileTivoli Configuration Manager 24, 25


installation 11, 33, 38


installation 14


uninstallation 40

Index 333

log file (continued)TWS4APPS_installationname_accessmethod^8.4.log,

twsappsinst 35, 40


installation 13


uninstallation 38


installation 17


uninstallation 39


twsappsinst 40









twsappsinst.log 35, 40

logon groupSAP R/3 113

Mmanaging

Business Warehouse InfoPackage and process chain 164

CA-7 job 231

JES job 229

SAP extended agent job running 115


mappingTivoli Workload Scheduler and SAP job states 145

mapping job statusPeopleSoft 85

MAX_TIME: Oracle option 64

MAXWAIT, SYSTSIN variable 215

MCMAGENT 62

MCMAGENT.opts 62

mcmagent.opts fileentry syntax 63

example 65

overview 63

MCMAGENT.opts filedefinition 43

mcmagent.propertiesfile 247

MCSSTORAGE, SYSTSIN variable 215

messageOracle access method 313

PeopleSoft access method 276, 314

SAP R/3 access method 278

twsappsinst installation 266

z/OS gateway 270

message helpexplanation 265

operator response 265

see also 265

system action 265

message numbercomponent code 264

messagescode 263

error 264

format 263

messages (continued)help 265

informational 264

number 263

numeric identifier 264

severity code 264

text 265

Tivoli Workload Scheduler for Applications component

codes 264

warning 264

MIN_TIME: Oracle option 64

modifyingglobal options file 46


monitoringJES job 230

SAP event defined as event rule 190

SAP event defined as internetwork dependency, XBP

2.0 185

multiple application servers, PeopleSoft 77

mvsca7.propertiesfile 247

mvsjes.opts filedefinition 43

mvsjes.propertiesfile 247

mvsopc.opts filedefinition 43

mvsopc.propertiesfile 247

NN component code

PeopleSoft access method 276

nameglobal options file 43


National Language supportR/3 203

new copyre-running jobs SAP 137

numbermessages 263

numeric identifiermessage definition 264

OO component code

SAP R/3 access method 278

occurrence stateTivoli Workload Scheduler for z/OS 233

old copyre-running jobs SAP 137

OPCINTERFACE, SYSTSIN variable 216

OPCMSGCLASS, SYSTSIN variable 216

OPCSUBSYSTEM, SYSTSIN variable 216

operating systems, supported 5

operation overviewTivoli Workload Scheduler for z/OS 232

operation stateTivoli Workload Scheduler for z/OS 233

operator passwordencrypting on PeopleSoft 77


operator responsemessage element 265

OPERCMDS 213

Option Editorglobal options file modifying 44


local options file modifying 44

Simple view 45

Table view 45

Text view 45

vopted.sh command 44

option inheritance r3batchdefinition 44

optionslanguage pack response file 18

language pack silent installation 18

product response file 15

product silent installation 15

R/3 National Language support 203

to install Software Package Blocks 22, 23

options file 74

global 43

local 43

mcmagent.opts 63


PeopleSoft 75, 77

SAP 91, 103

SAP example 111

z/OS 221

ORA_APP_TOPDIR: Oracle option 64

Oracle access methodmessage 313

Oracle E-Business Suiteaccess method options 63

completing installation 31

defining job 67

features 61

introduction 61

job state 69

options file 63

parameters to define job 68

password encryption 66


roles and responsibilities 61

software requirements 61

task string parameters 68

ORACLE_HOME: Oracle option 64

ORACLE_SID: Oracle option 64

other z/OS jobstask definition, z/OS 225

overviewIBM Tivoli Workload Scheduler for Applications 3


PeopleSoft 73

Tivoli Workload Scheduler for Applications for SAP 89

z/OS 207

PP component code

Oracle access method 313

parameteraccess_method.trace.handlers.traceFile.fileDir 248

access_method.trace.tracers.level 247

access_method.trace.traces.logging 248

properties file 247, 248

r3batch.trace.handlers.traceFile.maxFiles 248

parameter (continued)r3batch.trace.handlers.traceFile.maxFileSize 248


SAP job definition 129

SAP R/3 dynamic job definition 151

parameter for twsappsinstaccess method 27

inst_dir 27, 29, 35, 40

install language pack 29

lang 27, 29, 35, 40

language 29

twsuser 27, 29, 35, 40

u 26, 29, 35, 40

uninst 40

upgrade 35

v 26, 29, 35, 40

parameters for twsappsinstinstall IBM Tivoli Workload Scheduler for Applications 27

parent-childSAP R/3 feature 175

parent-child featureR/3 180

password encryption 66

PASSWORD: Oracle option 64

PATH: Oracle option 64

PEERADDRESS, SYSTSIN variable 216

PeopleSoftaccess method options 75

batch processing ID 78

configuration tasks 75

connecting to multiple application servers 77

creating job 83

defining job 83

encrypting operator password 77

functional overview 74


introduction 73

ITWS_PSXA project 78

job definition 83

job status mapping 85

job tracking 74

options file 75, 77

overview 73




security 74



PeopleSoft access methodmessage 276, 314

placeholderfor job interception in template file 179

SAP job 185

PORT, SYSTSIN variable 216

prerequisitesinstallation 6

software 6

PRINTER_NAME: Oracle option 64

process chaincreating Tivoli Workload Scheduler job 164

managing 164

schedule options 164

user authorization 164

process chain jobdisplaying details 142

rerunning 138

Index 335

productbefore installing 9

installation prerequisites 6

installing 10

overview 3

silent installation 14

silent uninstallation 40

software prerequisites 6


upgrading 33

product support. locating 220

programcomposer 50, 57

program componentz/OS 212

projectITWS_PSXA PeopleSoft 78

properties fileaccess_method.trace.handlers.traceFile.fileDir 248

access_method.trace.tracers.level 247

customizing 247

DEBUG_MAX 247

DEBUG_MID 247

DEBUG_MIN 247

parameter 247, 248

PS_DISTSTATUS, PeopleSoft option 75

psagent 74, 77

psagent.opts filedefinition 43

psagent.propertiesfile 247

PSFT_OPERATOR_ID,PeopleSoft option 75

PSFT_OPERATOR_PWD, PeopleSoft option 75

PSJOAPATH, PeopleSoft option 76

publications xv

PUTLINE, SYSTSIN variable 216

pwdcrypt programencrypting user password 77

QQLIMIT, SYSTSIN variable 216

RR/3

BDC wait 173

configuration file 249

National Language support 203

parent-child feature 180


Unicode support 93

r3batch definitionoption inheritance 44

r3batch inheritancedefinition 44

r3batch.optsoptions file 103

SAP R/3 103

r3batch.opts filedefinition 43

r3batch.propertiesfile 247

r3evman command 190

r3evmon event configuration file 257

RACF authorization, setting 211

raising SAP event 145

re-running jobnew copy, SAP 137

old copy, SAP 137

refreshingSAP variant 126

rerunning jobprocess chain 138

SAP 137

response filelanguage pack options 18

product options 15

tws4appslangsilent.txt, silent installation 17


RETRYCOUNT, z/OS option 222

return code mappingconsiderations 240

example 240, 242

feature 239

file name 244

file, creating 239

intercepted job 245


parameter 239

PeopleSoft 241

R/3 242

syntax 239

RFC profileSAP R/3 95

RFC userSAP R/3 261

RFC user passwordSAP R/3 101

roles and tasksOracle E-Business Suite 61

PeopleSoft 73

SAP 91

z/OS 208

RUNLOCATION, PeopleSoft option 76

SSAP

re-running jobs 137

rerunning job 137

SAP eventcommitting by external request 187

defining as event rule 189

defining as internetwork dependency 186, 188

filtering in security file 192

monitoring 190

placeholder job for internetwork dependencies 185

prerequisite to define a rule 190

prerequisites for defining as internetwork

dependency 185

r3evman command 190

r3evmon configuration file 257

raising 145

SAP jobdefining dynamically 149

deleting 144

displaying details 141

editing 128

example of defining dynamically 160

killing 147

placeholder 185

task string 129


SAP job (continued)variable substitution 160

verifying status 144

SAP R/3ABAP step definition attribute 156

ABAP/4 modules, importing 98

access method 91

application server 112

authorization profile 95

Business Information Warehouse support 163

Business Warehouse components 163

calendars, exporting 181

changing password, RFC user 101

committing event by external request 187

common options 106

configuration 95

configuration options 103

configuration options usage 111

connecting 112

connection 261

control file 98

correction and transport files 98

creating job containing InfoPackage 164

creating job containing process chain 164

creating RFC user 95

customization procedure 95

data file 98

defining event as event rule 189

defining event as internetwork dependency 186, 188

defining event rule based on IDocs 196

defining job 115, 129

defining job dynamically 149

defining variant 126

deleting variant 126

dynamic job definition example 160

dynamic job definition parameter description 151

dynamic job definition syntax 150

encrypting user password 111

event defined as event rule 189

event defined as internetwork dependency 186, 188


event rule prerequisite 190

exporting calendars, business scenario 181

exporting factory calendars 181

extended agent job 115

external command step definition attribute 159

external program step definition attribute 159

factory calendars, exporting 181

features 90

filtering events in security file 192

global options 103

IDoc record used in event rule 196

InfoPackage schedule options 164

installing ABAP modules 95


introduction 89

job interception 175

job interception and parent-child 175

jobs dynamic definition 150

local options 105

logon group 113

mapping between definition and resolution of internetwork

dependency 187

monitoring event 190

options file 91, 103, 111

options National Language support 203


SAP R/3 (continued)placeholder job for internetwork dependencies 185

prerequisite to define event rule 190

process chain schedule options 164

r3evman command 190

r3evmon configuration file 257

refreshing variant 126

RFC user password 101


security file, filtering events 192

setting a filter in security file 192

setting interception criteria 176

setting variant 126


supported code pages 204

supported configurations 204

task string 129

task string parameter 169


Transaction PFCG 96

Transaction SU02 96

updating variant 126

variable substitution 160

viewing variant 126

SAP R/3 access methodmessage 278

SAP R/3 table criteriasetting template file 177

setting using the Job Scheduling Console 176

script file 224

security 212

PeopleSoft 74

security file, filtering SAP events 192

see alsomessage element 265

server groupbalancing SAP R/3 workload 144

SERVER_NAME_LIST, PeopleSoft option 76

SETPROGcommand 211

settingjob interception 176

job interception using interception criteria and template

files 176

SAP R/3 table criteria using the Job Scheduling

Console 176

SAP variant 126

template file 177

setup programs 8

setup.bincommand for installation 11, 13

severity codemessage definition 264

silent installationadding a language 17


IBM Tivoli Workload Scheduler for Applications

options 15

language pack 17

language pack options 18

silent uninstallationlanguage pack 39

Tivoli Workload Scheduler for Applications 40

softwarecomponents 62

Software Package Blocksoptions to install the language pack 23

Index 337

Software Package Blocks (continued)options to install the product 22

Software Package Blocks (.spb)to install IBM Tivoli Workload Scheduler for

Applications 19

to install language pack 22

software prerequisitesTivoli Workload Scheduler for Applications 6

software requirementsOracle E-Business Suite 61

PeopleSoft 73

SAP 89

z/OS 207

start up 213

stateCA-7 job 231

JES job 229

SAP job 145

status mappingPeopleSoft job 85

structureinstallation CD 8

submittingextended agent job 58

SUBSYS, SYSTSIN variable 216

support, product, locating 220

supportedcode pages, SAP R/3 204

configuration, SAP R/3 204

Internet Protocol version 6 9

IPv6 9

operating system 5

SVCDUMP, SYSTSIN variable 216

syntaxdefining SAP jobs dynamically 150

mcmagent.opts file 63



twsappsinst 27, 29, 35, 40

syntax diagrams, how to read xvi

system actionmessage element 265

SYSTSIN variableCA7INTERFACE 213

CA7NAME 213

CA7OPTIONS 213

CA7SPAN(9999) 214

CA7SUBSYSTEM 214

CA7USER 214

CA7WAIT 214

COMPLETIONCODE 215

DEBUG 215

JESCMDCHR 215

JESINTERFACE 215

MAXWAIT 215

MCSSTORAGE 215

OPCINTERFACE 216

OPCMSGCLASS 216

OPCSUBSYSTEM 216

PEERADDRESS 216

PORT 216

PUTLINE 216

QLIMIT 216

SUBSYS 216

SVCDUMP 216

TCPIPSTACK 216

TCPNAME 217

SYSTSIN variable (continued)TERMINATOR 217

WTP 217

ZOSV1R2 217

Ttable criteria SAP R/3

setting template file 177

setting using the Tivoli Job Scheduling Console 176

tapeunloading files, z/OS gateway installation 209

task definition syntaxCA-7 job, z/OS 223

JES job, z/OS 223

other z/OS jobs 225


z/OS 223

task string parametersOracle E-Business Suite job 68

PeopleSoft job 84

SAP job 131

SAP R/3 job 129, 169

TCP/IP: stack 216

TCP/IP: version 207

TCPIPSTACK, SYSTSIN variable 216

TCPNAME, SYSTSIN variable 217

technical overviewz/OS 229

technical trainingSee Tivoli technical training

template filecreating 177

description 177

setting placeholders for job interception 179

TERMINATOR, SYSTSIN variable 217

textmessages 265

THREE_TIER_DB: Oracle option 64

timing considerationz/OS job 234

Tivoli Configuration Managerinstalling IBM Tivoli Workload Scheduler for

Applications 19

Java Runtime Environment (JRE) installing 24

language pack installing 25

log file 24, 25

Option Editor installing 25

PeopleSoft installing 25

SAP R/3 installing 24


Applications 39

Tivoli Dynamic Workload Consoleaccessibility xv

Tivoli Message Standard 263

Tivoli Software Distributioninstalling IBM Tivoli Workload Scheduler for

Applications 19

Tivoli technical training xvi

Tivoli Workload Scheduler for Applicationssoftware prerequisites 6

Tivoli Workload Scheduler for z/OSapplication state 233

occurrence state 233

operation overview 232

operation state 233


Tivoli Workload Scheduler for z/OS jobchecking 233

launching 232

managing 232


trace filetrace-mcmagent.log 248

trace-mvsca7.log 248

trace-mvsjes.log 248

trace-mvsopc.log 248

trace-psagent.log 248

trace-r3batch.log 248

tracing utilityconfiguring 247

trackingPeopleSoft job 74

trainingSee also Tivoli technical training

technical xvi

Transaction PFCGSAP R/3 96

Transaction SU02SAP R/3 96

troubleshooting 251

EEO0778E 261

extended agentjob log 260

PeopleSoft, job submission fails 260

PeopleSoft, local options file rights 260

extendend agentOracle, job submission fails 260

installingISMP displays error on Solaris 251

ISMP on HP-UX 11.0 251

ISMP on HP-UX version 11i 251

language pack displays Java exception 252

language pack remains in pending state 252

mvsjes, S047 abend 260

r3batchmodifying job step error 259

monitoring IDoc events 258, 259

monitoring SAP events 257, 258

scheduling SAP jobs 259

r3evmonmonitoring events increases memory consumption 258

restarting process of subchain 260

SAP R/3connection 261

error defining internetwork dependency 261

uninstalling 253, 254

ISMP 256

some packages remains in catalog 255

z/OS 235

TWS_MAX_WAIT_TIME, PeopleSoft option 76

TWS_MIN_WAIT_TIME, PeopleSoft option 76

TWS_RETRY, PeopleSoft option 76

TWS4APPS_installationname_accessmethod^8.4.loglog file 40

log file for ISMP installation 38

log file for ISMP installation wizard 33

log file for silent installation 14

log file for silent uninstallation 40

log file using twsappsinst 35

log file, ISMP installation 11

TWS4APPS_installationname_LANGS^8.4.loglog file for ISMP installation wizard 13

log file for ISMP uninstallation 38

TWS4APPS_installationname_LANGS^8.4.log (continued)log file for silent installation 17


log file for twsappsinst 40

tws4apps_ismp.loglog file, ISMP installation 11, 33

log file, silent installation 14

tws4apps_uninst_ismp.loglog file for ISMP installation 38


tws4appslangs_uninst.loglog file for silent uninstallation 39

log file ISMP uninstallation 38

tws4appslangs.loglog file 17

log file, ISMP installation 13

tws4appslangsilent.txtinstallation response file for language pack 17

tws4appssilent.txtinstallation response file for product 14

TWSA_SCHED_METH, PeopleSoft option 76

twsappsinstadding a language 28

adding an IBM Tivoli Workload Scheduler for Applications

access method 26

example to install language pack 30

example to install Tivoli Workload Scheduler for

Applications 28

example to uninstall version 8.4 41

example to upgrade to version 8.4 36


Applications 26


syntax 27, 29, 35, 40


Applications 40


Applications 35

usage parameter 26, 29, 35, 40

twsappsinst parameterinstall language pack 29

lang 29, 35, 40

language 29

twsappsinst 29, 35, 40

twsuser 29, 35, 40

u 26, 29, 35, 40

uninst 40

upgrade 35

v 26, 29, 35, 40

twsappsinst parametersaccess method 27

install IBM Tivoli Workload Scheduler for Applications 27

lang 27

twsappsinst 27

twsuser 27

twsappsinst.loglog file for twsappsinst 40

log file using twsappsinst 35

TWSMETH_CP: Oracle option 64

TWSMETH_LANG: Oracle option 64

twsusertwsappsinst parameter 27, 29, 35, 40

TWSXA_CP: Oracle option 65

TWSXA_INLINE_CI, PeopleSoft option 76

Index 339

Uu


Unicode supportR/3 93

uninsttwsappsinst parameter 40

uninstallation log fileTWS4APPS_installationname_accessmethod^8.4.log, ISMP

installation 38


uninstallation 40


twsappsinst 40


uninstallation 38


uninstallation 39


twsappsinst 40





twsappsinst.log 40

uninstallation procedures 37

uninstaller.bincommand for uninstallation 38, 39, 40

uninstallingIBM Tivoli Workload Scheduler for Applications with ISMP

wizard 38

IBM Tivoli Workload Scheduler for Applications with silent

installation 40


Tivoli Configuration Manager 39


twsappsinst 40


language pack with silent uninstallation 39

procedures 37

Tivoli Workload Scheduler for Applications 36

z/OS gateway 211

unloadingfiles from the CD, z/OS gateway installation 208

files from the tape, z/OS gateway installation 209

updatingSAP variant 126

upgradetwsappsinst parameter 35

upgradingaccess method with ISMP wizard 33


IBM Tivoli Workload Scheduler for Applications with ISMP

wizard 33


twsappsinst 35

usagetwsappsinst 27, 29, 35, 40

user authorizationsBusiness Warehouse InfoPackage 164

Business Warehouse process chain 164

user passwordencrypting on PeopleSoft 77

encrypting on SAP 111

USERID: Oracle option 65

UTF8CMDLINE: Oracle option 65

Vv


variable substitutionSAP R/3 160

variant SAP R/3defining 126

deleting 126

refreshing 126

setting 126

updating 126

viewing 126

verifying statusSAP job 144

version supported, operating system 5

viewingSAP variant 126

vopted.shcommand 44

Wwarning messages, definition 264

wizard ISMPadding a language 13

adding an access method 11


Applications 11



Applications 38

uninstalling language pack 38


Applications 33

workload, balancing SAP R/3 144

workstation for extended agent, defining withcommand line 50

ISPF 52


WORKSTATION NAME_MCMAGENT.opts 62

wremovspcommand 39

WTP, SYSTSIN variable 217

Zz/OS

access method options 221

configuring 221

configuring gateway 210

defining job 222

dependency on jobs 225

features 207

installing 208

installing gateway 208

introduction 207

JCL to unload the tape 209

program component 212


setting APF authorizations 211

setting RACF authorizations 211


task definition syntax 223, 224, 225

technical overview 229

troubleshooting 235

uninstalling gateway 211


z/OS gatewaydownloading fix pack files by FTP 218

messages 270

unloading files from CD 208

unloading files from tape 209

z/OS jobdiagnostic information 235

timing consideration 234

z/OS program componentEEWTCP00 212

EEWTCP02 212

zOS job dependencies 225

ZOSV1R2, SYSTSIN variable 217

Index 341


��

Printed in USA

SC32-1278-05

Spine information:

IBM

Ti

voli

Wor

kloa

d Sc

hedu

ler f

or Ap

plic

atio

ns

Vers

ion

8.4

(Rev

ised

Ju

ne 20

08)

User

’s Gu

ide

��

�

Documents

T l Workload Scheduler Applications - Ordonnancement ...ordonnancement.org/pdf_c3212785.pdf · Tivoli ® Workload Scheduler for Applications User’s Guide Version 8.4 (Revised June