tivoli workload automation: driving tivoli workload scheduler for … · 2018. 6. 6. · i b m t iv...

IBM Tivoli Workload Automation

Driving Tivoli Workload Scheduler forz/OSVersion 9.2 (Revised September 2017)

SC32-1266-09

IBM

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

This edition applies to version 9, release 2, modification level 0 SPE of Tivoli Workload Scheduler for z/OS(program number 5698-T08) and to all subsequent releases and modifications until otherwise indicated in neweditions.

© Copyright IBM Corporation 1999, 2014.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

© Copyright 2017 HCL Technologies Limited.

Contents

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

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

About this publication . . . . . . . . xiiiWho should read this publication. . . . . . . xiiiPublications . . . . . . . . . . . . . . xivUsing LookAt to look up message explanations . . xivAccessibility . . . . . . . . . . . . . . xivTivoli technical training . . . . . . . . . . xvSupport information . . . . . . . . . . . xvConventions used in this publication . . . . . . xvHow to read syntax diagrams . . . . . . . . xv

Part 1. Programming interfaces . . . 1

Chapter 1. The program interface (PIF) . 3Program interface samples . . . . . . . . . . 3Related tools . . . . . . . . . . . . . . 3

Batch command interface tool . . . . . . . 3IBM Tivoli Workload Scheduler for z/OS controllanguage. . . . . . . . . . . . . . . 3

Communicating with EQQYCOM . . . . . . . 4Required data sets . . . . . . . . . . . . 5Optional data set . . . . . . . . . . . . . 5Error messages . . . . . . . . . . . . . 5Parameter overview . . . . . . . . . . . . 6

Action code. . . . . . . . . . . . . . 7Resource code . . . . . . . . . . . . . 7Data area . . . . . . . . . . . . . . 8Argument names and values . . . . . . . . 8Communication block . . . . . . . . . . 9Return code . . . . . . . . . . . . . 10

Sequence of requests . . . . . . . . . . . 10Data area description and format . . . . . . . 10

Header format . . . . . . . . . . . . 10Data record format . . . . . . . . . . . 11

Date considerations. . . . . . . . . . . . 12Internal date representation . . . . . . . . 12Date arguments in PIF applications . . . . . 12Updating application description run cycles withPIF . . . . . . . . . . . . . . . . 13

Security considerations . . . . . . . . . . 13Running user-written programs compiled for olderscheduler versions . . . . . . . . . . . . 14Overview of request types . . . . . . . . . 14DELETE request . . . . . . . . . . . . . 16

Action code . . . . . . . . . . . . . 16Resource code . . . . . . . . . . . . 16Data area . . . . . . . . . . . . . . 17Arguments . . . . . . . . . . . . . 17Communication block address . . . . . . . 24Return code . . . . . . . . . . . . . 24

EXECUTE request . . . . . . . . . . . . 24


INIT request . . . . . . . . . . . . . . 25Action code . . . . . . . . . . . . . 25Resource code . . . . . . . . . . . . 25Data area . . . . . . . . . . . . . . 25Arguments . . . . . . . . . . . . . 25Communication block address . . . . . . . 27Return code . . . . . . . . . . . . . 27

INSERT request . . . . . . . . . . . . . 27Action code . . . . . . . . . . . . . 28Resource code . . . . . . . . . . . . 28Data area . . . . . . . . . . . . . . 29Arguments . . . . . . . . . . . . . 29Communication block address . . . . . . . 37Return code . . . . . . . . . . . . . 37

LIST request . . . . . . . . . . . . . . 37Action code . . . . . . . . . . . . . 37Resource code . . . . . . . . . . . . 37Data area . . . . . . . . . . . . . . 38Arguments . . . . . . . . . . . . . 39Communication block address . . . . . . . 48Return code . . . . . . . . . . . . . 48

MODIFY request . . . . . . . . . . . . 49Action code . . . . . . . . . . . . . 49Resource code . . . . . . . . . . . . 49Data area . . . . . . . . . . . . . . 49Arguments . . . . . . . . . . . . . 49Communication block address . . . . . . . 58Return code . . . . . . . . . . . . . 58

OPTIONS request . . . . . . . . . . . . 58Action code . . . . . . . . . . . . . 58Resource code . . . . . . . . . . . . 58Data area . . . . . . . . . . . . . . 59Arguments . . . . . . . . . . . . . 59Communication block address . . . . . . . 62Return code . . . . . . . . . . . . . 62

REPLACE request . . . . . . . . . . . . 62Action code . . . . . . . . . . . . . 62Resource code . . . . . . . . . . . . 63Data area . . . . . . . . . . . . . . 63Arguments . . . . . . . . . . . . . 63Communication block address . . . . . . . 64Return code . . . . . . . . . . . . . 64

RESET request . . . . . . . . . . . . . 64Action code . . . . . . . . . . . . . 64Resource code . . . . . . . . . . . . 64Data area . . . . . . . . . . . . . . 64Arguments . . . . . . . . . . . . . 64Communication block address . . . . . . . 64Return code . . . . . . . . . . . . . 64

SELECT request . . . . . . . . . . . . . 65

© Copyright IBM Corp. 1999, 2014 iii


SETSTAT request . . . . . . . . . . . . 76Action code . . . . . . . . . . . . . 76Resource code . . . . . . . . . . . . 76Data area . . . . . . . . . . . . . . 76Arguments . . . . . . . . . . . . . 76Communication block address . . . . . . . 77Return code . . . . . . . . . . . . . 77

TERM request . . . . . . . . . . . . . 77Action code . . . . . . . . . . . . . 77Resource code . . . . . . . . . . . . 77Data area . . . . . . . . . . . . . . 77Arguments . . . . . . . . . . . . . 77Communication block address . . . . . . . 77Return code . . . . . . . . . . . . . 78

JCL preparation using PIF . . . . . . . . . 78Substituting variables . . . . . . . . . . 78Simulating variable substitution . . . . . . 79

Chapter 2. The ApplicationProgramming Interface (API) . . . . . 81Communicating with IBM Tivoli WorkloadScheduler for z/OS . . . . . . . . . . . . 81

CPI-C support provided by IBM Tivoli WorkloadScheduler for z/OS . . . . . . . . . . . 82

API buffer layouts . . . . . . . . . . . . 83APP - Fixed section. . . . . . . . . . . 84APPOBJ - Object section . . . . . . . . . 86APPSEL - Selection section . . . . . . . . 88APPVAL - Selection value section . . . . . . 89APPFLD - Field section . . . . . . . . . 90APPDAT - Data section . . . . . . . . . 91

Specifying object names . . . . . . . . . . 91Selecting object instances . . . . . . . . . . 92

Specifying key types . . . . . . . . . . 92Specifying selection criteria . . . . . . . . 93Broadcasting events . . . . . . . . . . 93

Selecting object fields to update or retrieve . . . . 94Return codes and reason codes generated by IBMTivoli Workload Scheduler for z/OS . . . . . . 94

Return codes and reason codes generated in thefixed section (APP) . . . . . . . . . . . 94Return codes and reason codes generated in theobject section (APPOBJ) . . . . . . . . . 95

Security . . . . . . . . . . . . . . . 96APPC and RACF . . . . . . . . . . . 96IBM Tivoli Workload Scheduler for z/OS andRACF . . . . . . . . . . . . . . . 96

Part 2. Programming tools . . . . . 99

Chapter 3. Batch command interfacetool. . . . . . . . . . . . . . . . 101Online tools . . . . . . . . . . . . . . 101The batch command interface . . . . . . . . 101

Input to batch command interface . . . . . 101BCIT output . . . . . . . . . . . . . 104Instructions . . . . . . . . . . . . . 105COPY . . . . . . . . . . . . . . . 106DELETE . . . . . . . . . . . . . . 108EXPORT . . . . . . . . . . . . . . 116GROUPDEF support . . . . . . . . . . 117IMPORT . . . . . . . . . . . . . . 117INSERT . . . . . . . . . . . . . . 119LIST . . . . . . . . . . . . . . . 129LISTSTAT . . . . . . . . . . . . . 137MODIFY . . . . . . . . . . . . . . 139OPTIONS . . . . . . . . . . . . . 145REPLACE . . . . . . . . . . . . . 146SELECT . . . . . . . . . . . . . . 147SETSTAT . . . . . . . . . . . . . . 155

Chapter 4. Control Language (OCL) 157What you can do using OCL . . . . . . . . 157Advantages of OCL . . . . . . . . . . . 158Summary of OCL instructions . . . . . . . . 158Customizing OCL . . . . . . . . . . . . 161

Specifying the initialization parameters . . . . 163Example 1 . . . . . . . . . . . . . 163Example 2 . . . . . . . . . . . . . 163Example 3 . . . . . . . . . . . . . 163Example 4 . . . . . . . . . . . . . 164Obtaining access authorization . . . . . . 164Logging executed instructions . . . . . . . 165Specifying OCL instructions . . . . . . . 165Specifying input arrival dates and times . . . 166Description of OCL instructions . . . . . . 169INIT . . . . . . . . . . . . . . . 222JSUACT . . . . . . . . . . . . . . 223KILLJOB . . . . . . . . . . . . . . 224KILLREC . . . . . . . . . . . . . . 226LABEL . . . . . . . . . . . . . . 228MODCOND . . . . . . . . . . . . . 228MODOP . . . . . . . . . . . . . . 230NOP . . . . . . . . . . . . . . . 235OPSTAT . . . . . . . . . . . . . . 236PROMPTN . . . . . . . . . . . . . 239PROMPTY . . . . . . . . . . . . . 241RELEASE. . . . . . . . . . . . . . 243RELOP . . . . . . . . . . . . . . 245RELSUCC . . . . . . . . . . . . . 247SET. . . . . . . . . . . . . . . . 249Concatenation operators . . . . . . . . . 249Built-In Functions . . . . . . . . . . . 249

SETUPD . . . . . . . . . . . . . . . 251SRSTAT . . . . . . . . . . . . . . . 252UNNOP . . . . . . . . . . . . . . . 255UPD . . . . . . . . . . . . . . . . 256WSSTAT . . . . . . . . . . . . . . . 257WTO . . . . . . . . . . . . . . . . 259Requirements . . . . . . . . . . . . . 259Sample job and procedure . . . . . . . . . 259

EQQYRJCL sample job . . . . . . . . . 259EQQYRPRC sample procedure . . . . . . 260

Messages . . . . . . . . . . . . . . . 261Message format . . . . . . . . . . . 261

iv Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

Part 3. Appendixes . . . . . . . . 263

Appendix A. Program interface recordformat . . . . . . . . . . . . . . 265TOD fields . . . . . . . . . . . . . . 265Application description (resource codes AD,ADCOM). . . . . . . . . . . . . . . 266

ADCIV - Interval definition for conditionalexternal predecessor segment . . . . . . . 266ADCOM - Common segment . . . . . . . 267ADDEP - Dependency segment . . . . . . 268ADCNC - Condition segment . . . . . . . 269ADCNS - Condition dependency segment . . . 269ADEXT - Extended name segment . . . . . 270ADKEY - Key segment . . . . . . . . . 270ADOP - Operation segment . . . . . . . 270ADRE - Remote job information segment . . . 272ADRUN - Run cycle segment . . . . . . . 273ADSAI - Operation system automationinformation segment . . . . . . . . . . 275ADSR - Special resource segment. . . . . . 276ADUSF - User field segment . . . . . . . 277ADXIV - Interval definition for externalpredecessor segment . . . . . . . . . . 277

All workstations closed (resource code AWSCL) 278AWSCL - All workstations closed intervalsegment . . . . . . . . . . . . . . 278

Calendar (resource codes CL, CLCOM) . . . . . 278CLCOM - Common segment . . . . . . . 279CLSD - Specific date segment . . . . . . . 279CLWD - Weekday segment . . . . . . . . 280

Current plan condition (resource codes CPCOND,CPCONDCO) . . . . . . . . . . . . . 280

CPCOND - Condition segment . . . . . . 280CPSIMP - Condition dependency segment. . . 281

Current plan occurrence (resource code CPOC) . . 281CPOC - Current plan occurrence segment . . . 281

Current plan operation (resource codes CPOP,CPOPCOM) . . . . . . . . . . . . . . 283

CPCPR - Conditional predecessor segment . . 284CPCSU - Conditional successor segment . . . 284CPEXT - Operation extended name segment . . 285CPOP - Common segment . . . . . . . . 285CPOPSRU - Special resource usage segment . . 290CPPRE - Predecessor segment . . . . . . . 291CPREND - Distributed remote job info segment 292CPRENZ - z/OS remote job info segment . . . 293CPSAI - Operation system automationinformation segment . . . . . . . . . . 293CPSUC - Successor segment . . . . . . . 294CPSR - Special resource segment . . . . . . 295CPREC - Operation recovery segment . . . . 295

Current plan status (resource code CPST) . . . . 296CPST - Common segment . . . . . . . . 296

Current plan operation user field (resource codesCPUSRF, CPUSRFELEM) . . . . . . . . . 297

CPUSRF - Operation user field segment . . . 297Current plan workstation (resource codes CPWS,CPWSCOM) . . . . . . . . . . . . . . 298

CPWS - Common segment . . . . . . . . 298

CPIVL - Current plan workstation open intervalsegment . . . . . . . . . . . . . . 300CPOPT - workstation description recordsegment . . . . . . . . . . . . . . 301

Current plan virtual workstation destination(resource codes CPWSV, CPWSVCOM) . . . . . 302

CPWSV - Common segment . . . . . . . 302CPVIVL - Current plan virtual workstationdestination open interval segment . . . . . 304

Current plan special resource (resource codes CSR,CSRCOM) . . . . . . . . . . . . . . 304

CSRCOM - Current plan resource commonsegment . . . . . . . . . . . . . . 305CSRIVL - Current plan special resource intervalsegment . . . . . . . . . . . . . . 307CSRIWS - Current plan resource interval"connected" workstation . . . . . . . . . 307CSRDWS - Current plan resource default"connected" workstation . . . . . . . . . 307

ETT - Event triggered tracking criteria segment . . 308Dates generated by run cycle rules (resource codeGENDAYS) . . . . . . . . . . . . . . 308JCL setup variables (resource codes JCLPREP,JCLPREPA . . . . . . . . . . . . . . 309

JSVC - Common segment . . . . . . . . 309JSVV - Variable definition segment . . . . . 310

JCL variable table (resource codes JCLV,JCLVCOM) . . . . . . . . . . . . . . 310

JCLVC - Common segment . . . . . . . . 310JCLVV - Variable definition segment . . . . . 311JCLVD - Dependency segment. . . . . . . 312

Job control language (resource codes JS, JSCOM) 312JS - Job control language segment . . . . . 312

Job log (resource code JLCOM) . . . . . . . 313JLCOM - Common segment . . . . . . . 313

Long-term plan occurrence (resource codes LTOC,LTOCCOM) . . . . . . . . . . . . . . 314

LTOC - Common segment . . . . . . . . 314LTOP - Operation segment . . . . . . . . 315LTCPRE- Conditional predecessor segment. . . 316LTCSUC- Conditional successor segment. . . . 316LTPRE - Predecessor segment . . . . . . . 316LTSUC - Successor segment . . . . . . . 317

Operator instruction (resource codes OI, OICOM) 317OI - Operator instruction segment . . . . . 318

Period (resource codes PR, PRCOM). . . . . . 318PR - Period segment . . . . . . . . . . 319

Run cycle group (resource codes RG, RGCOM) . . 320RGCOM - Common segment . . . . . . . 320RGRUN - Run cycle segment . . . . . . . 321

Special resource (resource codes SR, SRCOM) . . 322Workstation description (resource codes WS,WSCOM). . . . . . . . . . . . . . . 325

WSCOM - Common segment . . . . . . . 326WSDEST – Destination segment . . . . . . 327WSIVL - Open interval segment . . . . . . 328WSSD - Specific date segment . . . . . . . 328WSWD - Weekday segment . . . . . . . 328WSAM - Workstation access method segment 329WSOPT - workstation description recordsegment . . . . . . . . . . . . . . 329

Contents v

Virtual workstation destination description(resource codes WSV, WSVCOM) . . . . . . . 330

WSVCOM - Common segment . . . . . . 330WSVIVL - Open interval segment . . . . . 332WSVSD - Specific date segment . . . . . . 332WSVWD - Weekday segment . . . . . . . 332

Appendix B. API object fields . . . . 335Current plan status object . . . . . . . . . 335Current plan operation object . . . . . . . . 336Current plan special resource object . . . . . . 341Current plan workstation object . . . . . . . 342Current plan open interval object. . . . . . . 344Current plan operation event object . . . . . . 344Current plan OPINFO event object . . . . . . 346Current plan special resource event object . . . . 347Current plan backup event object. . . . . . . 348Current plan workstation event object . . . . . 349

Appendix C. Sample library(SEQQSAMP) . . . . . . . . . . . 351IBM Tivoli Workload Scheduler for z/OSApplication Programming Interface . . . . . . 351

API buffer examples . . . . . . . . . . 351IBM Tivoli Workload Scheduler for z/OS programinterface . . . . . . . . . . . . . . . 352

JS data set maintenance . . . . . . . . . 352JCL variable substitution . . . . . . . . 352Current plan and LTP actions . . . . . . . 353Other PIF samples. . . . . . . . . . . 353

Notices . . . . . . . . . . . . . . 355Trademarks . . . . . . . . . . . . . . 356

Index . . . . . . . . . . . . . . . 359

vi Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

Figures

1. Program interface parameters . . . . . . . 72. Program interface arguments in TSO command

notation . . . . . . . . . . . . . . 93. Program interface data area example . . . . 11

4. Example of arguments for processing a list 675. Example of a send buffer layout for a GET

request . . . . . . . . . . . . . . 846. Application flow example . . . . . . . 163

© Copyright IBM Corp. 1999, 2014 vii

viii Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

Tables

1. Comparison of Date Representations . . . . 132. Access Authority for Program Interface

Requests . . . . . . . . . . . . . 133. Program Interface Resources and the

Corresponding IBM Tivoli Workload Schedulerfor z/OS Fixed Resources Used for CheckingAuthorization . . . . . . . . . . . . 14

4. Records Using a Common Segment . . . . 155. Delete AD Arguments . . . . . . . . . 176. Delete AWSCL Arguments . . . . . . . 187. Delete CL Arguments . . . . . . . . . 188. Delete CPCOND Arguments . . . . . . . 189. Delete CPOC Arguments . . . . . . . . 18

10. Delete CPOP Arguments . . . . . . . . 1811. Delete CPPRE Arguments . . . . . . . . 1812. Delete CPSIMP Arguments . . . . . . . 1913. Delete CPSR Arguments . . . . . . . . 2014. Delete CPSUC Arguments. . . . . . . . 2015. Delete CPUSRF Arguments . . . . . . . 2016. Delete ETT Arguments . . . . . . . . . 2017. Delete IVL Arguments . . . . . . . . . 2118. Delete JCLV Arguments . . . . . . . . 2119. Delete JL Arguments . . . . . . . . . 2120. Delete JS, JSCOM Arguments . . . . . . 2121. Delete LTOC Arguments . . . . . . . . 2122. Delete LTCPRE Arguments . . . . . . . 2223. Delete LTPRE Arguments . . . . . . . . 2224. Delete OI Arguments . . . . . . . . . 2225. Delete PR Arguments . . . . . . . . . 2226. Delete RG Arguments . . . . . . . . . 2327. Delete SR Arguments . . . . . . . . . 2328. Delete VIVL Arguments . . . . . . . . 2329. Delete WS Arguments . . . . . . . . . 2330. Delete WSV Arguments . . . . . . . . 2431. Insert CPOC Arguments . . . . . . . . 3032. Insert CPCOND Arguments . . . . . . . 3133. Insert CPOP Arguments . . . . . . . . 3134. Insert CPPRE Arguments . . . . . . . . 3235. Insert CPSAI Arguments . . . . . . . . 3336. Insert CPSIMP Arguments . . . . . . . 3337. Insert CPSR Arguments . . . . . . . . 3438. Insert CPSUC Arguments . . . . . . . . 3439. Insert CPUSRF Arguments . . . . . . . 3540. Insert IVL Arguments . . . . . . . . . 3541. Insert JCLPREP Arguments . . . . . . . 3542. Insert JCLV Arguments. . . . . . . . . 3543. Insert LTOC Arguments . . . . . . . . 3644. Insert LTPRE Arguments . . . . . . . . 3645. Insert VIVL Arguments . . . . . . . . 3646. List ADCOM and ADKEY Arguments. . . . 4147. List AWSCL Arguments . . . . . . . . 4148. List CLCOM Arguments . . . . . . . . 4249. List CPCONDCO Arguments . . . . . . 4250. List CPOC Arguments . . . . . . . . . 4251. List CPOPCOM Arguments . . . . . . . 4352. List CPOPSRU Arguments . . . . . . . 44

53. List CPWSCOM Arguments . . . . . . . 4454. List CPWSVCOM Arguments . . . . . . 4555. List CSRCOM Arguments . . . . . . . . 4556. List ETT Arguments. . . . . . . . . . 4557. List GENDAYS Arguments . . . . . . . 4558. List JCLVCOM Arguments . . . . . . . 4659. List JLCOM Arguments . . . . . . . . 4660. List JSCOM Arguments . . . . . . . . 4761. List LTOCCOM Arguments . . . . . . . 4762. List OICOM Arguments . . . . . . . . 4763. List PRCOM Arguments . . . . . . . . 4764. List RGCOM, RGKEY Arguments . . . . . 4765. List SRCOM Arguments . . . . . . . . 4866. List WSCOM Arguments . . . . . . . . 4867. List WSVCOM Arguments . . . . . . . 4868. Modify CPCOND Arguments . . . . . . 5069. Modify CPEXT Arguments . . . . . . . 5070. Modify CPOC Arguments. . . . . . . . 5071. Modify CPOP Arguments . . . . . . . . 5172. Modify CPREND Arguments. . . . . . . 5373. Modify CPRENZ Arguments . . . . . . . 5374. Modify CPSAI Arguments . . . . . . . 5475. Modify CPUSRF Arguments . . . . . . . 5476. Modify CPWS Arguments. . . . . . . . 5577. Modify CPWSV Arguments . . . . . . . 5578. Modify CSR Arguments . . . . . . . . 5679. Modify IVL Arguments . . . . . . . . 5780. Modify LTOC Arguments . . . . . . . . 5781. Modify VIVL Arguments . . . . . . . . 5782. Replace AD Arguments . . . . . . . . 6383. Select AD, ADCOM Arguments . . . . . . 6884. Select AWSCL Arguments . . . . . . . . 6985. Select CL, CLCOM Arguments . . . . . . 6986. Select CPCOND, CPCONDCO Arguments 6987. Select CPOC Arguments . . . . . . . . 7088. Select CPOP, CPOPCOM Arguments . . . . 7089. Select CPUSRF Arguments . . . . . . . 7190. Select CPWS, CPWSCOM Arguments . . . . 7291. Select CPWSV, CPWSVCOM Arguments 7292. Select CSR, CSRCOM Arguments . . . . . 7293. Select ETT Arguments . . . . . . . . . 7394. Select JCLPREP Arguments . . . . . . . 7395. Select JCLPREPA Arguments . . . . . . . 7396. Select JCLV, JCLVCOM Arguments . . . . . 7397. Select JLCOM Arguments . . . . . . . . 7398. Select JS, JSCOM Arguments . . . . . . . 7499. Select LTOC, LTOCCOM Arguments . . . . 74

100. Select OI, OICOM Arguments . . . . . . 74101. Select PR, PRCOM Arguments . . . . . . 74102. Select RG, RGCOM Arguments . . . . . . 75103. Select SR, SRCOM Arguments . . . . . . 75104. Select WS, WSCOM Arguments . . . . . . 75105. Select WSV, WSVCOM Arguments . . . . . 75106. Setstat CPSIMP Argument . . . . . . . 77107. Contents of a Send Buffer . . . . . . . . 83108. App-Fixed Section . . . . . . . . . . 85

© Copyright IBM Corp. 1999, 2014 ix

109. APPOBJ-Object Section. . . . . . . . . 87110. APPSEL-Selection Section . . . . . . . . 89111. APPVAL-Selection Value Section . . . . . 90112. APPFLD-Field Section . . . . . . . . . 90113. APPDAT-Data Section . . . . . . . . . 91114. API Object Names . . . . . . . . . . 91115. Operators That You Can Specify in the

APPSEL Section . . . . . . . . . . . 93116. Subresource Protection for Requests through

the API . . . . . . . . . . . . . . 97117. Positional parameters that can be passed with

the Batch Command Interface . . . . . . 101118. Access Authorizations . . . . . . . . 164119. Input Arrival Date and Time Keywords 166120. How OCL Uses the IADATE, IATIME, and IA

Keywords. . . . . . . . . . . . . 167121. IBM Tivoli Workload Scheduler for

z/OS-supplied Variables . . . . . . . . 169122. Keywords Used in the Add Instruction 169123. Keywords used in the Addcond Instruction 171124. Keywords used in the Addop Instruction 175125. Keywords used in the Addpred Instruction 179126. Keywords used in the Addres Instruction 181127. Keywords used in the Addsimp Instruction 183128. Keywords used in the Chgextname

Instructions . . . . . . . . . . . . 186129. Keywords used in the Chgjob Instructions 188130. Keywords used in the Chgopsai Instructions 189131. Keywords used in the Chkappl Instruction 192132. Chkdate Instruction Variables . . . . . . 195133. Keywords used in the Compl Instruction 203134. Keywords used in the Del Instruction 205135. Keywords used in the Delcond Instruction 207136. Keywords used in the Delpred Instruction 208137. Keywords used in the Delres Instruction 210138. Keywords used in the Delsimp Instruction 212139. Keywords used in the Force Instruction 215140. Keywords used in the Hold Instruction 218141. Keywords used in the Init Instruction 222142. Keywords used in the JSUACT Instruction 223143. Keywords used in the Killjob Instruction 224144. Keywords used in the Killrec Instruction 226145. Keywords used in the Modcond Instruction 228146. Keywords used in the Modop Instructions 230147. Operations Details that can be modified 233148. Keywords used in the Nop Instruction 235149. Keywords used in the Opstat Instruction 236150. Keywords used in the PROMPTN Instruction 239151. Keywords used in the PROMPTY Instruction 241152. Keyword used in the Release Instruction 243153. Keywords used in the Relop Instruction 246154. Keywords used in the Relsucc Instruction 247155. Keywords used in the Srstat Instruction 252156. Keywords used in the Unnop Instruction 255157. Keywords used in the Wsstat Instruction 257158. Clock value setting at the start of different

years . . . . . . . . . . . . . . 265159. Clock value setting at different time interval 265160. ADCIV Control Block . . . . . . . . . 266161. ADCOM Control Block . . . . . . . . 267162. ADDEP Control Block . . . . . . . . 268

163. ADEXT Control Block. . . . . . . . . 270164. ADOP Control Block . . . . . . . . . 271165. ADRE Control Block . . . . . . . . . 272166. ADRUN Control Block . . . . . . . . 273167. Run Cycle Offsets . . . . . . . . . . 274168. Rule Definition . . . . . . . . . . . 275169. ADSAI Control Block . . . . . . . . . 275170. ADSR Control Block . . . . . . . . . 276171. ADUSF Control Block. . . . . . . . . 277172. ADXIV Control Block . . . . . . . . . 277173. AWSCL Control Block . . . . . . . . 278174. CLCOM Control Block . . . . . . . . 279175. CLSD Control Block . . . . . . . . . 279176. CLWD Control Block . . . . . . . . . 280177. CPOC Control Block . . . . . . . . . 282178. CPEXT Control Block . . . . . . . . . 285179. CPOP Control Block . . . . . . . . . 285180. CPOPSRU Control Block . . . . . . . . 290181. CPPRE Control Block . . . . . . . . . 291182. CPREND Control Block . . . . . . . . 292183. CPRENZ Control Block . . . . . . . . 293184. CPSAI Control Block . . . . . . . . . 294185. CPSUC Control Block . . . . . . . . . 294186. CPSR Control Block . . . . . . . . . 295187. CPREC Control Block . . . . . . . . . 295188. CPST Control Block . . . . . . . . . 297189. CPUSRF Control Block . . . . . . . . 297190. CPUSRFELEM Control Block . . . . . . 298191. CPWS Control Block . . . . . . . . . 299192. CPIVL Control Block . . . . . . . . . 300193. CPOPT Control Block . . . . . . . . . 301194. CPWSV Control Block . . . . . . . . 302195. CPVIVL Control Block . . . . . . . . 304196. CSRCOM Control Block . . . . . . . . 305197. CSRIVL Control Block . . . . . . . . 307198. CSRIWS Control Block . . . . . . . . 307199. CSRDWS Control Block . . . . . . . . 307200. ETT Control Block . . . . . . . . . . 308201. GNDAY Control Block . . . . . . . . 308202. JSVC Control Block . . . . . . . . . 309203. JSVV Control Block . . . . . . . . . 310204. JCLVC Control Block . . . . . . . . . 310205. JCLVV Control Block . . . . . . . . . 311206. JCLVD Control Block . . . . . . . . . 312207. JS Control Block . . . . . . . . . . 312208. JLCOM Control Block. . . . . . . . . 313209. LTOC Control Block . . . . . . . . . 314210. LTOP Control Block . . . . . . . . . 316211. LTPRE Control Block . . . . . . . . . 317212. LTSUC Control Block . . . . . . . . . 317213. OI Control Block . . . . . . . . . . 318214. PR Control Block . . . . . . . . . . 319215. Period Origin Dates . . . . . . . . . 319216. Period Interval End Dates . . . . . . . 320217. RGCOM Control Block . . . . . . . . 320218. RGRUN Control Block . . . . . . . . 321219. Rule Definition . . . . . . . . . . . 322220. SRCOM Control Block . . . . . . . . 323221. SRIVL Segment . . . . . . . . . . . 324222. SRIWS Segment. . . . . . . . . . . 325223. SRDWS Segment . . . . . . . . . . 325

x Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

224. WSCOM Control Block . . . . . . . . 326225. WSDEST Control Block . . . . . . . . 327226. WSIVL Control Block . . . . . . . . . 328227. WSSD Control Block . . . . . . . . . 328228. WSWD Control Block . . . . . . . . . 329229. WSAM Control Block . . . . . . . . . 329230. WSOPT Control Block . . . . . . . . 329231. WSVCOM Control Block . . . . . . . . 331232. WSVIVL Control Block . . . . . . . . 332233. WSVSD Control Block . . . . . . . . 332234. WSWD Control Block . . . . . . . . . 333235. CP_STATUS Object Fields . . . . . . . 335

236. CP_OPERATION Object Fields. . . . . . 336237. CP_RESOURCE Object Fields . . . . . . 341238. CP_WORK_STATION Object Fields . . . . 342239. CP_OPEN_INTERVAL Object Fields . . . . 344240. CP_OPER_EVENT Object Fields . . . . . 344241. CP_OPINFO_EVENT Object Fields . . . . 346242. CP_SR_EVENT Object Fields . . . . . . 347243. BACKUP_EVENT Object Fields . . . . . 348244. CP_WS_EVENT Object Fields . . . . . . 349245. SEQQSAMP Library Members for

Programming Interfaces and the API. . . . 351

Tables xi

xii Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

About this publication

IBM® Tivoli® Workload Automation: Developer's Guide: Driving IBM Tivoli WorkloadScheduler for z/OS shows you how to use the programming interfaces to IBM TivoliWorkload Scheduler for z/OS® to help you plan, schedule, and monitor work inthe production department of your computer installation.

Your workload can run on various platforms, but you control it from a centralz/OS system that runs the Tivoli Workload Scheduler for z/OS controller.

This guide is part of a set of guides that allows you to program many aspects ofworking with the products in the Tivoli Workload Automation family. These guidescomprise:v Tivoli Workload Automation: Developer's Guide: Driving Tivoli Workload Scheduler for

z/OS, SC32-1266

v Tivoli Workload Automation: Developer's Guide: Driving Tivoli Workload Automation,SC23-9608

v Tivoli Workload Automation: Developer's Guide: Extending Tivoli WorkloadAutomation, SC14-7623

Note: If you control your z/OS controller using Dynamic Workload Console,information about the programming interfaces you can use with the DynamicWorkload Console are available in both of the other Developer's Guides in the set.

The term scheduler, when used in this publication, refers to Tivoli WorkloadScheduler for z/OS. The term DB2®, when used in this publication, refers toDATABASE 2 and DB2 Universal Database™.

The term z/OS is used in this publication to mean z/OS and OS/390® operatingsystems. Where the term OS/390 appears, the related information applies only toOS/390 operating systems.

Who should read this publicationThis publication is for users who write application programs that request servicesfrom Tivoli Workload Scheduler for z/OS.

This publication documents the programming interface (PIF) and the applicationprogramming interface (API). To use PIF you must know job control language(JCL) and have a good working knowledge of a programming language, forexample, assembler or PL/I. You can use programming languages that supportz/OS and OS/390 linkage conventions and that can load and delete an assemblerprogram.

To use the API, you require a knowledge of Advanced Program-to-ProgramCommunication (APPC). You must be able to write application transactionprograms (ATPs) that use the services of APPC. Because the API is implementedusing a subset of CPI-C (Common Programming Interface for Communications)verbs, you must be able to write ATPs that use CPI-C.

© Copyright IBM Corp. 1999, 2014 xiii

PublicationsThe Tivoli Workload Automation product is supported by a set of publications.

For a list of publications in the Tivoli Workload Automation product library, seePublications under Reference in the product documentation.

For a list of terms used in the Tivoli Workload Automation product, see Glossaryunder Reference in the product documentation.

Using LookAt to look up message explanationsLook up explanations for most of the IBM messages you encounter, as well as forsome system abends (an abnormal end of a task) and codes.

LookAt is an online facility that lets you look up explanations for most of the IBMmessages you encounter, as well as for some system abends (an abnormal end of atask) and codes. Using LookAt to find information is faster than a conventionalsearch because in most cases LookAt goes directly to the message explanation.

You can use LookAt from the following locations to find IBM messageexplanations for z/OS elements and features, z/VM®, VSE/ESA, and Clusters forAIX® and Linux:v The Internet. You can access IBM message explanations directly from the LookAt

website at http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/.v Your z/OS TSO/E host system. You can install code on your z/OS system to

access IBM message explanations, using LookAt from a TSO/E command line(for example, TSO/E prompt, ISPF, or z/OS UNIX System Services runningOMVS).

v Your Microsoft Windows workstation. You can install code to access IBMmessage explanations on the IBM Online Library z/OS Software Products CollectionKit (SK3T-4270), using LookAt from a Microsoft Windows DOS command line.

v Your wireless handheld device. You can use the LookAt Mobile Edition with ahandheld device that has wireless access and an Internet browser (for example,Internet Explorer for Pocket PCs, Blazer, or Eudora for Palm OS, or Opera forLinux handheld devices). Link to the LookAt Mobile Edition from the LookAtwebsite.

You can obtain code to install LookAt on your host system or Microsoft Windowsworkstation from a disk on your IBM Online Library z/OS Software ProductsCollection Kit (SK3T-4270), or from the LookAt website (click Download, and selectthe platform, release, collection, and location that suit your needs). Moreinformation is available in the LOOKAT.ME files available during the downloadprocess.

AccessibilityAccessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully.

With this product, you can use assistive technologies to hear and navigate theinterface. You can also use the keyboard instead of the mouse to operate allfeatures of the graphical user interface.

xiv Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/

For full information with respect to the Dynamic Workload Console, see theAccessibility Appendix in the IBM Tivoli Workload Scheduler User’s Guide andReference.

Tivoli technical trainingTivoli provides technical training.

For Tivoli technical training information, refer to the following IBM TivoliEducation website:

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

Support informationIBM provides several ways for you to obtain support when you encounter aproblem.

If you have a problem with your IBM software, you want to resolve it quickly. IBMprovides 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 tocontact IBM Software Support.

For more information about these three ways of resolving problems, see theappendix on support information in Tivoli Workload Scheduler: Troubleshooting Guide.

Conventions used in this publicationConventions used in this publication.

The publication uses several typeface conventions for special terms and actions.Technical changes to the text are indicated by a vertical line to the left of thechange. These conventions have the following meanings:

Information type Style convention Example

Commands All capital letters CREATE

References in the text tofields on panels

All capital letters QUANTITY

File and directory names,input you should type inpanel fields

Monospace MYAPPLICATION

First time new termintroduced, publication titles

Italics Application

How to read syntax diagramsSyntax diagrams help to show syntax in a graphical way.

About this publication xv

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

Throughout this publication, syntax is described in diagrams like the one shownhere, which describes the SRSTAT TSO command:

►► SRSTAT ' resource name 'OPCA

SUBSYS ( subsystem name )MSTR

►

►KEEP

AVAIL ( RESET )NOYES

KEEPDEVIATION ( amount )

RESET

►

►KEEP

QUANTITY ( amount )RESET

YESCREATE ( NO )

►

►0

TRACE ( trace level )

►◄

The symbols have these meanings:

►►─────The statement begins here.

──────►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 thepath 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:

►► STATEMENToptional item

►◄

v An arrow returning to the left above the item indicates an item that you canrepeat. If a separator is required between items, it is shown on the repeat arrow.

►► STATEMENT ▼

,

repeatable item ►◄

xvi Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

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 1required choice 2

►◄

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

►► STATEMENToptional choice 1optional choice 2

►◄

– A repeat arrow above a stack indicates that you can make more than onechoice from the stacked items:


,

optional choice 1optional choice 2optional choice 3

►◄


,

required choice 1required choice 2required choice 3

►◄

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

►► STATEMENTdefault

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

►► STATEMENT required choice 1option 1 option 2

required choice 2required choice 3

►◄

option 1

defaultoptional choice 1 ( alternative )

About this publication xvii

option 2

defaultoptional choice 2 ( alternative )

xviii Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

Part 1. Programming interfaces

© Copyright IBM Corp. 1999, 2014 1

2 Tivoli Workload Automation: Driving Tivoli Workload Scheduler for z/OS

Chapter 1. The program interface (PIF)

This chapter describes the Tivoli Workload Scheduler for z/OS program interface(PIF), which lets a user-written program issue various requests to the IBM TivoliWorkload Scheduler for z/OS subsystem. For example, you can automate actionsthat you perform through the IBM Tivoli Workload Scheduler for z/OS dialogs.

The program interface supports these basic requests:

Database requests

v Read and update information from the application description andoperator instruction databases.

v Read information from the workstation description and calendardatabases.

LTP requestsRead and update occurrences in the LTP data set.

Current plan requestsRead and update this information in the current plan data set:v Occurrencesv Operationsv Workstations

The program interface is supported using a IBM Tivoli Workload Scheduler forz/OS-supplied communication subroutine, EQQYCOM.

Program interface samplesThe IBM Tivoli Workload Scheduler for z/OS sample library shipped with the IBMTivoli Workload Scheduler for z/OS programs contains many sample programsthat use the program interface function. These programs will execute successfullywith a few minor changes to suit your installation. You can continue to run themas they are, or use them as a model to create your own programs. See Appendix C,“Sample library (SEQQSAMP),” on page 351 for a description of the PIF samplemembers provided in the SEQQSAMP library.

Related toolsIBM Tivoli Workload Scheduler for z/OS is delivered with some tools that takeadvantage of the PIF. These tools are provided as additional aids in the process ofautomating workload management with IBM Tivoli Workload Scheduler for z/OS.

Batch command interface toolA Batch Command Interface tool is supplied to perform some of the actionssupplied by the PIF interface by means of a batch command interface. See “Batchcommand interface tool” for more information about how to use this tool. Refer tothe EQQYCBAT sample for running this tool.

IBM Tivoli Workload Scheduler for z/OS control languageThe IBM Tivoli Workload Scheduler for z/OS Control Language (OCL) is a REXXprogram, EQQOCL, delivered in the IBM Tivoli Workload Scheduler for z/OSSEQQMISC library, that allows some of the IBM Tivoli Workload Scheduler for

© Copyright IBM Corp. 1999, 2014 3

z/OS data to be handled from a simple REXX-like interface. You use the tool byrunning EQQOCL as a compiled REXX program in a batch TSO environment. Youcan choose to run it in a separate job or as a step in your production JCL.

The tool is described in Chapter 4, “Control Language (OCL),” on page 157. Thefollowing members of IBM Tivoli Workload Scheduler for z/OS sample librariesare also supplied to help you use the tool:EQQYRJCL

A sample JCL to run the toolEQQYRPRC

A sample procedure to invoke EQQOCLEQQYRMSG

Contains the messages issued by the EQQOCL toolEQQYRPRM

A sample input parameter member

The OCL tool requires the IBM Compiler Libraries for REXX/370 Version 1.3.0,Program Number 5695-014. The Compiler Libraries must be installed on thesystem, and the TSO Compiler Programming Table, IRXCMPTM, must becustomized and the Compiler Libraries modules must be made available to TSO.Refer to the Compiler Libraries for REXX/370 manuals for more information.

The OCL tool calls the EQQSTOR program, available in the IBM Tivoli WorkloadScheduler for z/OS sample library member EQQRXSTG. If the WTO function isused, OCL calls the IPOWTO program, available in the scheduler sample librarymember EQQOCWTO. If the UPD function is used, OCL calls the EQQPIFTprogram available in IBM Tivoli Workload Scheduler for z/OS sample librarymember EQQPIFJV. This sample program requires the PL/I compiler and runtimelibraries. The EQQSTOR program, and optionally IPOWTO and EQQPIFTprograms, must be link-edited and made available to OCL at runtime.

Communicating with EQQYCOMRequests to IBM Tivoli Workload Scheduler for z/OS to perform particular actionsare calls to EQQYCOM, using normal z/OS linkage conventions.

You must create a program that calls EQQYCOM and provide it with the necessaryinstructions, such as a parameter list, to enable IBM Tivoli Workload Scheduler forz/OS to perform the required action. With each call to EQQYCOM, you can makeone IBM Tivoli Workload Scheduler for z/OS request.

EQQYCOM can be linked with the modules from which it is called, or it can becreated as a separate load module and control passed to it using the link macro. Ifyou create EQQYCOM as a separate load module and frequent calls are required,you should, for performance reasons, consider placing EQQYCOM in the link-packarea. All modules in the same job-step must be in an APF-authorized library. Thefirst module loaded at the start of the job-step must also be link-edited with theAPF-authorized attribute. In the TSO or TSO-batch environment, you need nothave the PIF program authorized.

Details of your request to IBM Tivoli Workload Scheduler for z/OS are aparameter list that you pass to EQQYCOM. Before passing control to EQQYCOM,you must load the address of your parameter list into general purpose register 1.

Note: If you want to run a PIF program from a IBM Tivoli Workload Scheduler forz/OS dialog, ensure that your PIF program is invoked as a separate task.


Otherwise, your dialog session will end when the PIF program has completed. Forexample, you can run a REXX exec that runs your PIF program using the ATTACHcommand.

Calling EQQYCOM from exits that are taken by the controller address space is notsupported and will cause unpredictable results if attempted.

Required data setsWhen you use the program interface, allocate the data sets identified by theseddnames to each address space where your program runs:

EQQMLIBIBM Tivoli Workload Scheduler for z/OS message library.

EQQMLOGData Set for messages from the program interface.

An extra message log is required for each additional INIT request madebefore a TERM request, or when PIF is invoked by a program or startedtask that already uses the EQQMLOG data set allocated to the calleraddress space. For detailed information, see “INIT request” on page 25.

Optional data setEQQYPARM

Parameter file for specifying the INIT initialization statement. EQQYPARMmust reference a sequential data set or a member of a partitioned data setwhose logical record length is 80 bytes.

The //EQQYPARM DD * notation followed by INIT statements is notallowed and might cause a system X'0C4' abend.

Note:

1. It is important that you also allocate the IBM Tivoli Workload Scheduler forz/OS diagnostic data set, EQQDUMP. Debugging information is written to thisdata set, for example, IBM Tivoli Workload Scheduler for z/OS control blocksand traces.

2. If you plan to run PIF applications many times per day from a long-runningnon-TSO address space (for example, NetView®), to prevent a storage shortagedo not specify the EQQYPARM ddname. Instead, specify the parameters eitherin the PIF application or in the controller INTFOPTS initialization statement.When you run a PIF application by specifying the EQQYPARM ddname, a TSOenvironment must be established each time and some of the resources remainallocated until the task ends. This might lead to a storage shortage, if thecommands are issued many times.

Error messagesWhen an error occurs in a request, messages are always written to the message logdata set allocated to the caller address space. The data set is either EQQMLOG orthat specified in the MLOGDDN argument of the INIT request. In certain cases,messages are also written to the EQQMLOG data set allocated to the IBM TivoliWorkload Scheduler for z/OS subsystem to which your requests are directed.

Chapter 1. The Program Interface 5

Errors related to the request itself (for example, a spelling error in a parameterargument) result in a message written only to the message log allocated to thecaller address space.

Errors related to the IBM Tivoli Workload Scheduler for z/OS subsystem (forexample, an error detected by IBM Tivoli Workload Scheduler for z/OS datavalidation) result in a brief message to the caller message log. A more detailedmessage about the error is written to the EQQMLOG allocated to the IBM TivoliWorkload Scheduler for z/OS subsystem.

Parameter overviewThe parameter list contains the necessary information for one request. Figure 1 onpage 7 illustrates the basic structure of the parameter list and the addressinglinkage to it.

The parameter list must always consist of seven fullwords, representing the sevenparameter types outlined here. Not all parameters are required for some requests,in which case you must set the parameter value to hexadecimal zeros. Acharacter-type parameter value that contains blanks also indicates that theparameter is omitted. The parameter list itself must not contain zeros.

Figure 1 on page 7 describes the parameter values that are referenced by theparameter address list.

An overview of the parameters follows. More detailed descriptions of the requiredparameters are given with the description of each request type.


Action codeThe first fullword in the parameter list is the address of the action code.

The action code describes the action to be performed. For example, to update arecord in one of the IBM Tivoli Workload Scheduler for z/OS databases, you usethe REPLACE action code.

Resource codeThe second fullword in the parameter list is the address of the resource code.

The resource code describes the IBM Tivoli Workload Scheduler for z/OS resourcethat the request is directed to. For example, to replace an application description inthe AD database, you use the AD resource code.

Parameter list address

Action code (8 char)

Resource code (8 char)

Register 1

Parameter List(7 fullwords)

Data area address

Header Data

Comm. block address

Return code

etc

Arg. name 1 (8 char)

Arg. name 2 (8 char)

etc

Arg. value 1 address

Arg. value 2 address

Action code address

Resource code address

Data area ptr address

Argument names address

Argument values address

Comm. block ptr address

Return code addressArg. value 1

Arg. value 2

Figure 1. Program interface parameters


Data areaThe third fullword in the parameter list is the address of a fullword that containsthe address of a data area.

A data area consists of the actual data involved in the request. If you are retrievinginformation from a database, EQQYCOM places the record in this area andprovides its address in the fullword whose address is in the parameter list.

Note: EQQYCOM might use the same piece of data area storage for successivedata retrieval requests, overwriting the storage area used for the previous requesteach time. Therefore, your program must copy the information to its own storagearea if it must be kept during later retrieval requests.

If you are writing information to a database, your program must build its owndata area and provide its address in the fullword whose address is in theparameter list.

Attention: When the data area is not used, the data area address in the parameterlist must be set to hexadecimal zero; failure to do so might cause unpredictableresults. Some programming languages might require special coding to achieve thistask; for example, in PL/I programs, use the SYSNULL built-in function.

The data area consists of a header, which describes the structure of the data record,and the data itself. “Data area description and format” on page 10 describes this inmore detail.

Argument names and valuesThe fourth and fifth fullwords in the parameter list are the addresses of theargument name list and argument value address list.

The arguments provide specific information about your request. An argument canconsist of an argument name alone, or an argument name and a matching argumentvalue. Some requests require only one or more argument names, and some requireargument names and values. If argument values are required, they are alwaysassociated one-for-one with the argument names.

Arguments can be compared to operands of a TSO command, where the argumentname corresponds to the parameter keyword, and the argument value correspondsto the parameter value. For example:


The parameter list contains two addresses for the arguments, one pointing to theargument name list and one pointing to the argument value address list.

The argument name list is an array of 8-byte character fields. Each field containsan argument name, is left justified. Blanks must appear to the right of theargument name if it is shorter than 8 characters. The list is terminated by anall-blank field.

The argument value address list contains a list of addresses that point to theargument values. For a character argument value, the length of the field should bethe same as that shown in the argument table. But, when a character argument isused as a selection argument, only the characters up to the first blank orcomparison operator are used. Date and time data types are processed in the sameway as character argument values. A numeric argument value must always be afullword.

The retrieval of a record from the application description database is an example ofhow arguments are used. Here, the arguments identify the particular recordrequired. The argument names identify the names of fields in the record, and theargument values identify the values of those fields for the record you want toretrieve (see Figure 2).

Sometimes, there might be a reason to specify the same argument more than once.For example, to get a list of active operations, you can specify argument nameSTATUS and C ≠ for the value, plus argument name STATUS and D ≠ for thevalue. You can specify an argument multiple times; up to 32 arguments can bedefined in the argument name list.

Communication blockThe sixth fullword in the parameter list is the address of a fullword containing theaddress of the communication block.

The first request to EQQYCOM must be an INIT request, which establishes acommunication session between EQQYCOM and your program. During INIT requestprocessing, EQQYCOM builds a communication block representing the session andreturns its address in the fullword whose address is in the parameter list. Thecommunication block address provided must remain unmodified during eachsubsequent call to EQQYCOM until the end of the session, so that EQQYCOM canidentify the session that requests are coming from.

Equivalent TSO command notation:

ADID(APPL1) STATUS(A) VALTO(950531)

Figure 2. Program interface arguments in TSO command notation


Return codeAfter each request, EQQYCOM provides a return code indicating if the requestwas successful or not.

The seventh fullword in the parameter list is the address of a fullword containingthe return code. This return code is also placed in register 15.

Sequence of requestsEach communication session must always start with an INIT request and end witha TERM request. There can be several requests between them.

When modifying the current plan, requests must be made as follows:1. With a series of requests, an MCP block is built containing all the necessary

information required for one modification of the current plan.2. With an EXECUTE request, information in the MCP block is used to actually

update the current plan data set.

Also, when modifying the current plan, you can make a series of requests thatrefer to the same occurrence. The first request identifies the occurrence, andfollowing requests can modify data related to that occurrence without needing tospecifically identify it each time. The program interface remembers what thecurrent occurrence is. Similarly, the program interface remembers the currentoperation and, once identified, a series of requests can be made that refer to it.

Other requests can be made in any sequence except where specifically noted. Forexample, you can produce a list of records with one request, which you can followwith one or more requests that select records from the list.

Data area description and formatRequests to EQQYCOM often involve either reading one or more records from aIBM Tivoli Workload Scheduler for z/OS database or data set, or writing them. Inboth cases, the record is placed in a data area and its address provided in afullword whose address is in the parameter list. When you are retrievinginformation, EQQYCOM places the required record in a data area and provides theaddress of this area. When you are writing information to a IBM Tivoli WorkloadScheduler for z/OS database or data set, your program must build its own dataarea and provide its address. Note that EQQYCOM might use the same piece ofstorage for data areas in successive data retrieval requests, overwriting the dataarea used for the previous request each time.

The data area consists of two parts:v The headerv The data record

Header formatThe header describes the segments in the record and their actual location withinthe record. The length and format of each segment type is fixed. For a descriptionof the segments, see Appendix A, “Program interface record format,” on page 265.

Note: For records retrieved with the SELECT request, the header always has alength that is a multiple of 32, with any unused header entries set to 00x. Forrecords created for the INSERT and REPLACE requests, it is not necessary to set


the header length to a multiple of 32, but if you do, you can use direct byte forbyte comparison of input and output records.

The header consists of one or more header entries, each entry describing onesegment in the data record. Each header entry is 16 bytes and consists of:

Segment name (8 characters)A character field containing the name of a segment. If this field is blank,this is the last header entry in the header.

Offset to segment (1 fullword)Offset to the start of this segment within the record from the start of theheader. If this data area is from a LIST or SELECT request and it is the lastheader entry (segment name is blanks), this field contains moreinformation about the request. This is further described under the detaileddescriptions of the requests later in this chapter.

Reserved (4 bytes)Reserved for use by IBM Tivoli Workload Scheduler for z/OS.

The header is terminated by a header entry with a blank segment name. Figure 3shows an example of a data area using an application description.

Data record formatEach data record handled by the program interface function consists of a subset ofthe full IBM Tivoli Workload Scheduler for z/OS record. Each record consists ofthe same fields that are available in the ISPF dialogs, in the same format. Yes/Nofields are single character fields, which contain either Y or N. Integer values arefullword fields.

The amount of information in a IBM Tivoli Workload Scheduler for z/OS recordcan vary enormously. For example, an application description can contain one runcycle and one operation, or it can contain many run cycles and many operations.The size of each record and its format can vary greatly. Because of this, theprogram interface function uses a header for each record. The header containsinformation about the record.

Each record consists of one or more segments representing different information inthat record. For example, an application description consisting of one run cycle andthree operations is described by a record consisting of one run cycle segment andthree operation segments. Also, one common segment always exists, which containsbasic information, such as the application name, owner, and validity date. The

Figure 3. Program interface data area example


common segment is always the first segment of the data record. Other segmentscan appear in any order except that segments that are logically related appeartogether. For example, in an application description record, the operation segments(ADOP) can appear in any order, but the dependency (ADDEP) and specialresource segments (ADSR) always follow immediately after the ADOP to whichthey belong.

Date considerationsIBM Tivoli Workload Scheduler for z/OS can handle dates up to 31 December2071. This high date is the default for application description valid-to and runcycle out-of-effect dates when you use the IBM Tivoli Workload Scheduler forz/OS dialogs.

Internal date representationInternally, IBM Tivoli Workload Scheduler for z/OS works with a two-digit yearformat, so dates are represented as 00 to 99. In order to handle dates before andafter 2000, IBM Tivoli Workload Scheduler for z/OS has chosen 72 as the base year.This means that, internally, 1972 is represented as 00, 1995 as 23, and 2071 as 99.

This internal date does not affect IBM Tivoli Workload Scheduler for z/OS dialogand report users. They always see the real date. However, PIF requests ofteninvolve reading or writing records in a IBM Tivoli Workload Scheduler for z/OSdatabase. These records contain dates in the internal two-digit format with baseyear 72. You use the PIFCWB and PIFHD parameters of the INTFOPTS statementor the CWBASE and HIGHDATE parameters of the INIT statement to define howyou want these dates to be presented to PIF applications.

PIFCWB and CWBASE values determine what base year IBM Tivoli WorkloadScheduler for z/OS uses when presenting dates to PIF applications. If you specify00, dates are presented as the last two digits of the real date. For example, 1995 ispresented as 95 and 2001 as 01. Note, however, that the PIFCWB and CWBASEparameters affect all dates except the default out-of-effect and valid-to dates. Thesedates are presented to PIF application as the value specified in the PIFHD andHIGHDATE parameters.

Refer to Tivoli Workload Scheduler for z/OS: Customization and Tuning, SC32-1265 formore details on these statements.

Date arguments in PIF applicationsYou might have PIF applications developed before year 2000 that use 991231 as thevalue of the VALTO argument to indicate the default valid-to date of the lastversion of the AD. The real default date is 31 December 2071. However, by usingthe PIFHD parameter of the INTFOPTS statement or the HIGHDATE parameter ofthe INIT statement to define the high date as 991231, you can use these existingPIF applications without updating them.

A good way to avoid specifying a specific date for default valid-to dates is todefine the PIFHD keyword of the INTFOPTS statement or the HIGHDATEkeyword of the INIT statement as a six-character string. IBM Tivoli WorkloadScheduler for z/OS will always interpret this as representing the default valid-todate.

Table 1 on page 13 gives an overview of the different date representations.


Table 1. Comparison of Date Representations

Real date Internal datePIF date (base 00,high date 711231)

PIF date (base 72,high date 991231)

1994/06/15 220615 940615 220615

2004/06/15 320615 040615 320615

2071/12/31 991231 711231 991231

Updating application description run cycles with PIFWhen you use the ISPF dialogs to update or create application descriptions, youspecify a run cycle out-of-effect date. Then IBM Tivoli Workload Scheduler forz/OS calculates the run cycle valid-to date by subtracting one day from theout-of-effect date. However, when you use PIF to update an AD you do not specifythe out-of-effect date, you specify the valid-to date. Then IBM Tivoli WorkloadScheduler for z/OS calculates the out-of-effect date by adding one day. If youspecify the valid-to date as the default high date, adding one day would make thedate higher than the highest allowed date. Therefore, when you specify the valid-todate in a PIF application as the default high date, IBM Tivoli Workload Schedulerfor z/OS takes the IBM Tivoli Workload Scheduler for z/OS high date as theout-of-effect date.

Security considerationsYou need authorization to use many of the program interface requests. If you donot have authority for the request you need, give the relevant access type andRACF® resource code to your IBM Tivoli Workload Scheduler for z/OSadministrator. Table 2 describes the access authority you need:

Table 2. Access Authority for Program Interface Requests

Program interface request Access type required

INITOPTIONSRESETTERM

None

LISTSELECT

Read

DELETEEXECUTEINSERTMODIFYREPLACESETSTAT

Update

You need authorization to access these IBM Tivoli Workload Scheduler for z/OSfixed resources:


Table 3. Program Interface Resources and the Corresponding IBM Tivoli WorkloadScheduler for z/OS Fixed Resources Used for Checking Authorization

Program interface resourceIBM Tivoli Workload Scheduler for z/OSfixed resource

ADCOM, AD, ADEXT, ADKEY, ADRE AD

AWSCL WSCL

CL, CLCOM CL

CPEXT, CPST, CPOC, CPOP, CPOPCOM,CPWS, CPWSV, CPWSCOM, CPWSVCOM,IVL, VIVL, MCPBLK

CP

CSR, CSRCOM, CPOPSRU SR

ETT ETT

JCLV, JCLVCOM JV

JS, JSCOM, JCLPREP, JCLPREPA, JL, JLCOM JS

LTOC, LTOCCOM LT

OI, OICOM OI

PR, PRCOM PR

RG, RGCOM RG

SR, SRCOM RD

WS, WSCOM, WSV, WSVCOM WS

For example, to list the intervals during which all workstations are closed, resourceAWSCL, you need READ access to the WSCL fixed resource.

Running user-written programs compiled for older scheduler versionsBefore you try to run a program compiled for a previous version of IBM TivoliWorkload Scheduler for z/OS, the program OBJ must be compiled, or at leastlink-edited, for the current IBM Tivoli Workload Scheduler for z/OS version.

Overview of request typesThe requests that you can make to the program interface are summarized here. Therequests are described in detail in the following sections and are arranged inalphabetical order.

DELETEDeletes data items.

EXECUTEPerforms an actual update of the current plan.

INIT Initializes the communication session between your program and the IBMTivoli Workload Scheduler for z/OS subsystem.

INSERTInserts new data items or additional information into existing data items.

LIST Retrieves a list of data items of a specified type using generic searcharguments.


MODIFYModifies data fields in the LTP or current plan, or identifies CP or LTPdata items for further modification.

OPTIONSSpecifies options to be used when performing PIF requests. You can usethese options to automatically resolve external dependencies when addingLTP or CP occurrences, improve the time taken to retrieve informationabout operations, request the address of the area where the message ID isreturned, and to prevent messages being written to the message log.

REPLACEReplaces an existing application description or operator instruction.

RESETCancels a series of modify current plan requests if performed before theEXECUTE request.

SELECTRetrieves a single data item in detail.

SETSTATModifies the status of a condition dependency. You can use it to change thecondition status from undecided to true or false, if the original status isundecided because of missing step-end information.

TERM Terminates the communication session between your program and the IBMTivoli Workload Scheduler for z/OS subsystem.

Table 4. Records Using a Common Segment

Arg names Length

ADCOM 192

AWSCL 80

CLCOM 96

CPOPCOM (*) 380

CPOPSRU (*) 96

CSRCOM (*) 240

CPWSCOM (*) 128

CPWSVCOM(*) 129

ETT 128

JCLVCOM 96

JLCOM 64

JSCOM 96

LTOCCOM 157

OICOM 96

PRCOM 96

RGCOM 160

SRCOM 204

WSCOM 128

WSVCOM 128

(*): You cannot specify this argument name to delete the entire record.


DELETE requestThe DELETE request deletes a record or record segment. If you delete a record thearguments identify the particular record to be deleted. If you want to delete onlysome information in an occurrence (for example, one of the operations in anoccurrence), you must first use a MODIFY request to identify the occurrence beforeyou use the DELETE request for the operation. Similarly, if you want to delete aspecial resource specification or a current plan condition for an operation, youmust use a MODIFY request to identify the occurrence and then use a MODIFYrequest to identify the operation, before using a DELETE for the special resource.

To delete an interval of a current plan workstation you must precede the DELETEIVL with a MODIFY CPWS to identify the workstation.

To delete the extended name of an operation you must use the MODIFY request.See “MODIFY CPEXT” on page 140 for details.

The DELETE request can be used to modify information in the current plan. Allrequests that cause a modification of the current plan require a later EXECUTErequest for the modification to actually take effect.

Action codeDELETE

Resource codeThe resource code specifies which record type or record segment you want todelete. You can specify these values:AD Application description recordAWSCL

All workstations closed recordCL Calendar recordCPCOND

Current plan conditionCPOC Current plan occurrence recordCPOP Current plan operation recordCPPRE

Current plan predecessor segmentCPSIMP

Current plan condition dependencyCPSR Current plan special resource segmentCPSUC

Current plan successor segmentCPUSRF

Current plan user field segmentETT Event triggered tracking criteria recordIVL Current plan workstation interval segmentJCLV JCL variable table recordJL JS file JOBLOG recordJS Job control language recordLTOC LTP occurrence recordLTCPRE

LTP conditional predecessor segmentLTPRE

LTP predecessor segmentOI Operator instruction record.


PR Period recordRG Run cycle group recordSR Special resource recordVIVL Current plan virtual workstation destination interval segmentWS Workstation description recordWSV Virtual workstation destination record

Data areaNot used.

ArgumentsThe arguments identify the particular record you want to delete. Two ways youcan do this are:v Specify field names of the record as argument names and specify the addresses

of field values, to identify the particular record you want to delete. The valuescan be:– Character values. A blank character terminates the field.– Numeric values, which must occupy a fullword.

You must specify sufficient arguments to uniquely identify a record. You can usea comparison operator after the argument values. The default, equals (=), isassumed if you do not.

v Specify the record type as an argument name and the address of the previouslyretrieved common segment as the argument value address, if you have alreadyretrieved the common segment of a record but you then want to delete theentire record. Table 4 on page 15 describes the record types that you can specifyas argument names.

Note: The values of PIF arguments as dates depend on the PIF base year, which isdefined by the PIFCWB keyword on the INTFOPTS statement, or the CWBASEkeyword of the INIT statement. The value of the VALTO argument for default highdate depends on the PIFHD keyword of the INTFOPTS statement or theHIGHDATE keyword of the INIT statement. Refer to Tivoli Workload Scheduler forz/OS: Customization and Tuning, SC32-1265 for more details on these statements.

Delete AD argumentsTable 5. Delete AD Arguments

Arg names Length Data type Description

ADID 16 Char Application description ID

GROUP 8 Char Authority group name

GROUPDEF 16 Char Group definition ID

OWNER 16 Char Owner ID

PRIORITY 4 Integer Priority

STATUS 1 Char Status: P=Pending A=Active

TYPE 1 Char Application type: A=ApplicationG=Group Default is A

VALFROM 6 Char YYMMDD Valid-from date

VALTO 6 Char YYMMDD Valid-to date


Note: IBM Tivoli Workload Scheduler for z/OS assumes application type A, if youdo not specify the TYPE argument name.

Delete AWSCL argumentsTable 6. Delete AWSCL Arguments


DATE 6 Char YYMMDD Date

Delete CL argumentsTable 7. Delete CL Arguments


CALENDAR 16 Char Calendar ID

Delete CPCOND arguments

Note: Always identify an operation with a MODIFY CPOP request before aDELETE CPCOND request.

Table 8. Delete CPCOND Arguments


CONDID 4 Integer Condition ID. Valid values are from1 to 999.

Delete CPOC argumentsTable 9. Delete CPOC Arguments



IA 10 Char YYMMDDHHMM Input arrival date and time

Delete CPOP argumentsTable 10. Delete CPOP Arguments


OPNO 4 Integer Operation number

Delete CPPRE argumentsTable 11. Delete CPPRE Arguments


PREADID 16 Char Predecessor application ID

PREIA 10 Char YYMMDDHHMM Predecessor input arrival date andtime

PREMAND 1 Char The predecessor is mandatory. Thevalue can be Y or N (default).Specify Y if the predecessor ismandatory.

PREOPNO 4 Integer Predecessor operation number


Note: When deleting an internal predecessor, only specify PREOPNO. Specify allarguments to delete an external mandatory predecessor. Omit PREMAND if thepredecessor is not mandatory.

Delete CPSIMP arguments

Note: Always identify an occurrence, an operation and a condition with:v An INSERT or MODIFY CPOC requestv An INSERT or MODIFY CPOP requestv An INSERT or MODIFY CPCOND request

before a DELETE CPSIMP request.

Table 12. Delete CPSIMP Arguments


PREADID 16 Char Predecessor application name

PREIA 10 Char Predecessor application inputarrival date and time

PREOPNO 4 Integer Predecessor operation number

PROCSTEP 8 Char Use it to define a step leveldependency. If the step is not in aprocedure, this parameter identifiesthe job step name, otherwise itidentifies the step name in the JCLprocedure. It must correspond tothe name of an EXEC PGM= statement.

STEPNAME 8 Char Use it in conjunction withPROCSTEP when defining a steplevel dependency, only if the step isin a procedure, to identify the nameof a step that invokes an in-streamor cataloged procedure. It mustcorrespond to the name of an EXECPROC= statement.

TYPE 2 Char Condition type:RC = To check the predecessorreturn codeST = To check the predecessorstatus

LOG 2 Char Logical operator:GE = Greater than or equal to.Valid only for RC condition type.GT = Greater than. Valid onlyfor RC condition type.LE = Less than or equal to. Validonly for RC condition type.LT = Less than. Valid only forRC condition type.EQ = Equal to.NE = Not equal to. Use it tospecify conditions on finalstatuses only.RG = Range.

VALRC 4 Char Return code value.


Table 12. Delete CPSIMP Arguments (continued)


VALRC2 4 Char Return code value, as secondboundary in a range expressed bythe RG logical operator.

VALST 1 Char Status, valid only for ST type

Delete CPSR argumentsTable 13. Delete CPSR Arguments


RESNAME 44 Char Special resource name

Delete CPSUC argumentsTable 14. Delete CPSUC Arguments


SUCADID 16 Char Successor application ID

SUCIA 10 CharYYMMDDHHMM

Successor input arrival date and time

SUCOPNO 4 Integer Successor operation number

Note: When deleting an internal successor, only specify SUCOPNO. All threearguments must be specified to delete an external successor.

Delete CPUSRF argumentsTable 15. Delete CPUSRF Arguments


UFNAME 16 Char User field name

Note: When deleting a user field, only specify UFNAME. The corresponding userfield value is also deleted.

Delete ETT argumentsTable 16. Delete ETT Arguments


ADID 16 Char Associated application ID

ETTNAME 44 Char Name of trigger

ETTTYPE 1 Char Type of trigger, 2 -> job 3 -> specialresource

Delete IVL argumentsAn interval can have information originating from the workstation description,indicator CPIVLDP in segment CPIVL is set to Y, or else to N. If an interval ischanged or created via the dialog or the program interface, the indicatorCPIVLMOD in CPIVL is set to Y, or else to N.


DELETE IVL only affects modifications. Intervals with CPIVLDP=Y remain after aDELETE, the interval is reset to the daily planning values and CPIVLMOD is set toN. Intervals with CPIVLDP=N are fully deleted.

Table 17. Delete IVL Arguments


FROM 10 Char YYMMDDHHMM Interval start date and time

Delete JCLV argumentsTable 18. Delete JCLV Arguments


JCLVTAB 16 Char JCL variable table ID

Delete JL argumentsTable 19. Delete JL Arguments


ADID 16 Char Application ID

IA 10 CharYYMMDDHHMM

Input arrival date and time

JOBNAME 8 Char z/OS Job name


WSNAME 4 Char Workstation name

Delete JS argumentsTable 20. Delete JS, JSCOM Arguments



IA 10 CharYYMMDDHHMM

Input arrival date and time

JOBNAME 8 Char z/OS Job name



Delete LTOC argumentsTable 21. Delete LTOC Arguments



IAD 6 Char YYMMDD Input arrival date

IAT 4 Char HHMM Input arrival time


Delete LTCPRE argumentsTable 22. Delete LTCPRE Arguments





PREADID 16 Char Conditional predecessor applicationID

PREIAD 6 Char YYMMDD Conditional predecessor input arrivaldate

PREIAT 4 Char HHMM Conditional predecessor input arrivaltime

Delete LTPRE argumentsTable 23. Delete LTPRE Arguments





PREADID 16 Char Predecessor application ID

PREIAD 6 Char YYMMDD Predecessor input arrival date

PREIAT 4 Char HHMM Predecessor input arrival time

Note: DELETE LTPRE is used only to delete external predecessors. No support isprovided in the long-term plan for internal dependencies.

Delete OI argumentsTable 24. Delete OI Arguments




Note: To delete both the operator instruction and any associated temporaryinstructions, issue a LIST OICOM request followed by this loop:1. A request with the OICOM segment as the argument2. A SELECT OICOM with argument NEXT.

Continue the loop until SELECT OICOM NEXT gives a return code greater than 0.

Delete PR argumentsTable 25. Delete PR Arguments


PERIOD 8 Char Period name

PRTYPE 1 Char Period type


Delete RG argumentsTable 26. Delete RG Arguments


RGID 8 Char Run cycle group ID

RGOWNER 16 Char Run cycle group owner

RGCALEND 16 Char Run cycle group calendar

RGVARTAB 16 Char Run cycle group variable table

RUNNAME 8 Char Run cycle name

RUNCAL 16 Char Run cycle calendar

RUNVTAB 16 Char Run cycle variable table

RUNSETID 8 Char Run cycle subset ID

Delete SR argumentsTable 27. Delete SR Arguments


RESGROUP 8 Char Special resource group ID

RESHIPER 1 Char DLF resource indicator

RESNAME 44 Char Special resource name

Delete VIVL argumentsIf an interval contains information originating from the Virtual WorkstationDestination description, the indicator CPVIVLDP in segment CPVIVL is set to Y,otherwise it is set to N. If an interval is changed or created using the dialog or theprogram interface, the indicator CPVIVLMOD in segment CPVIVL is set to Y,otherwise it is set to N.

DELETE VIVL only affects modifications. Intervals with CPVIVLDP=Y remain aftera DELETE, the interval is reset to the daily planning values and CPVIVLMOD isset to N. Intervals with CPVIVLDP=N are fully deleted.

Table 28. Delete VIVL Arguments


FROM 10 Char YYMMDDHHMM Interval start date and time

Delete WS argumentsTable 29. Delete WS Arguments



WSREP 1 Char Workstation reporting attribute

WSRETYPE 1 Char Remote engine type:D = distributed,Z = z/OSor blank

WSTWS 1 Char Y=fault tolerant workstationN=non-fault tolerant workstation

WSTYPE 1 Char Workstation type


Table 29. Delete WS Arguments (continued)


WSWAIT 1 Char WAIT workstation, Y or N

Delete WSV argumentsTable 30. Delete WSV Arguments


WSNAME 4 Char Virtual workstation name

WSDEST 8 Char Virtual workstation destination

Communication block addressThis is the address returned by INIT request processing, which must remainunmodified for all following requests.

Return codeWhen EQQYCOM returns control, this fullword shows the outcome of the request:

0 The request was successful.

4 The record; AD, AWSCL, CL, ETT, JCLV, JS, OI, PR, SR, WS, or WSV iscurrently being updated by another user. The record is not deleted.

8 The request was unsuccessful. An error message has been written to themessage log data set.

EXECUTE requestThe EXECUTE request causes an update of the current plan after one or moremodify, insert, or delete current plan requests are completed.

If you are changing more than one current plan occurrence or current planworkstation before an EXECUTE request, you must complete all changes to oneoccurrence or workstation before changing another. If you do not complete allchanges to one occurrence or workstation a message is issued and all modificationssince the last EXECUTE request are reset.

For changes to current plan resources, CSR, no EXECUTE is required.

Action codeEXECUTE

Resource codeMCPBLK

Data areaNot used.

ArgumentsNot used.


Communication block addressThis is the address returned by INIT request processing, which should remainunmodified for all following requests.

Return codeWhen EQQYCOM returns control, this fullword shows the outcome of the request:

0 The request was successful.

8 The request was unsuccessful. An error message has been written to themessage log data set.

INIT requestThe INIT request identifies the IBM Tivoli Workload Scheduler for z/OS subsystemrequired and initializes the communication session between this subsystem andyour program. It must always be the first request. The INIT request builds acommunication block. EQQYCOM returns its address to your program.

Through the parameter file EQQYPARM, the user might override the subsystemname specified in the INIT request, and set an LU name, a host name and a portnumber for TCP/IP communication, a TRACE level, and the DATINT flag.

The parameter file can be a sequential file, or a PDS allocated as://EQQYPARM DD DISP=SHR,DSN=OPCESA.SYS1.CNTL(YPARM)

Action codeINIT

Resource codeThe name of an active IBM Tivoli Workload Scheduler for z/OS subsystem towhich all following requests are directed.

Data areaNot used.

ArgumentsYou can specify arguments to:v Determine if a recovery environment is established. The recovery environment

consists of a SPIE exit routine and an ESTAE recovery routine, which, in case oferror, will dump certain storage areas and terminate execution. You can specifyargument name ESTAEI, ESTAER, LUNAME, or NOESTAE. Argument valuesare not required.

v Identify a message log that messages are written to.

Argument name=ACCOIDThe parameter that determines if the OI database is to be accessed when aLIST or SELECT request on CP operations is issued.

Argument value=accoidA 1-byte character field for the accoid: valid values are Y or N. Ymeans that the OI database is read (this is the default). N meansthat the OI database is not read.


|||

||||

Argument name=ESTAEIThe recovery environment is established at the INIT request. It remains ineffect until the TERM request. This is the default.

Argument name=ESTAERThe recovery environment is established and terminated for eachindividual request. This might be needed if, for example, your programhas a recovery environment dependent on the setting of a certain register,as in PLI.

Argument name=LUNAMEThis argument allows the user to specify a server or controller LU namefor the program interface session.

Argument value=lunameA 17-byte field for the LU name address, ending by a blank ifshorter than 17 bytes.

Argument name=NOESTAENo recovery environment is established.

Argument name=MLOGDDNThis argument identifies a message log that messages are written to, ratherthan the default message log, EQQMLOG.

Each INIT request requires its own message log. If you make more thanone INIT request before a TERM request, or if PIF is invoked by a programor started task that is already using EQQMLOG, specify MLOGDDN foreach additional INIT request. If MLOGDDN is not specified, andEQQMLOG is already in use, message EQQZ038E is written to theSYSLOG and the INIT request fails.

Argument value=ddnameAn 8-character field, left justified, which identifies the ddname ofthe data set that messages are written to.

Argument name=REMHOSTThe server host name for the program interface TCP/IP session.REMHOST and LUNAME are mutually exclusive.

Argument value=server hostnameA 52-byte field for the host name address, ending by a blank ifshorter than 52 bytes.

Argument name=REMPORTThe server port number for the program interface TCP/IP session.REMHOST and LUNAME are mutually exclusive.

Argument value=server port numberA 4-byte integer field for the port number: valid values are from 0to 65535.

Argument name=DUBPR

tivoli workload automation: driving tivoli workload scheduler for … · 2018. 6. 6. · i b m t iv...

Documents