z/OS Version 2 Release 3 MVS Using the Subsystem Interface IBM SA38-0679-30 Note Before using this information and the product it supports, read the information in “Notices” on page 567. This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated in new editions. Last updated: 2019-02-16 © Copyright International Business Machines Corporation 1988, 2017. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents List of Figures...................................................................................................... vii List of Tables........................................................................................................ ix About this document.............................................................................................xi Who should use this document...................................................................................................................xi How to use this document.......................................................................................................................... xi z/OS information..........................................................................................................................................xi How to send your comments to IBM.....................................................................xiii If you have a technical problem................................................................................................................xiii Summary of changes...........................................................................................xiv Summary of changes for z/OS Version 2 Release 3..................................................................................xiv Summary of changes for z/OS Version 2 Release 2...................................................................................xv z/OS Version 2 Release 1 summary of changes....................................................................................... xvi Chapter 1. Introduction to subsystems and the subsystem interface....................... 1 What is a subsystem?...................................................................................................................................1 What is the SSI?........................................................................................................................................... 1 Unique attributes of the SSI...................................................................................................................1 Types of subsystem requests.................................................................................................................2 Controlling SSI processing..................................................................................................................... 3 Why write your own subsystem?................................................................................................................. 3 What is a dynamic subsystem?....................................................................................................................4 Chapter 2. Making a request of a subsystem........................................................... 7 Setting up the environment......................................................................................................................... 7 Subsystem options block (SSOB)...........................................................................................................7 SSOB function dependent area..............................................................................................................7 Subsystem identification block (SSIB)...................................................................................................8 Making the request with the IEFSSREQ macro........................................................................................... 9 Checking the return code...........................................................................................................................10 Summary of steps...................................................................................................................................... 11 Chapter 3. SSI function codes your program can request...................................... 13 SSI function code descriptions..................................................................................................................13 Process SYSOUT data sets call — SSI function code 1........................................................................14 User destination validation/conversion — SSI function code 11........................................................ 36 Verify subsystem function call — SSI function code 15...................................................................... 41 Request job ID call — SSI function code 20........................................................................................ 46 Return job ID call — SSI function code 21...........................................................................................52 Request subsystem version information call — SSI function code 54................................................56 Scheduler facilities call — SSI function code 70................................................................................. 72 JES job information services— SSI function code 71..........................................................................81 Notify user message service call — SSI function code 75................................................................ 125 SYSOUT application program interface (SAPI) — SSI function code 79...........................................134 Extended status function call — SSI function code 80..................................................................... 173 JES properties — SSI function code 82............................................................................................. 239 JES device information services — SSI function code 83................................................................. 331 Modify job function call — SSI function code 85...............................................................................412 iii Chapter 4. Setting up your subsystem................................................................ 439 Function routines/function codes........................................................................................................... 439 Environment....................................................................................................................................... 439 Recovery and integrity....................................................................................................................... 440 Placement of function routines......................................................................................................... 440 Do You Need a Subsystem Address Space?........................................................................................... 441 Defining your subsystem......................................................................................................................... 441 Naming your subsystem.....................................................................................................................442 Passing parameters............................................................................................................................442 The primary subsystem......................................................................................................................442 Providing a routine to initialize your subsystem..................................................................................... 443 What your subsystem initialization routine can do........................................................................... 443 How to initialize your subsystem....................................................................................................... 444 Passing accounting parameters to your subsystem............................................................................... 445 Processing the SUBPARM option.......................................................................................................446 Example..............................................................................................................................................447 Chapter 5. Services for building and using your subsystem................................. 449 Adding your subsystem........................................................................................................................... 449 Using the IEFSSNxx parmlib member............................................................................................... 449 Using the IEFSSI macro..................................................................................................................... 450 Using the SETSSI command.............................................................................................................. 450 Initializing your subsystem......................................................................................................................450 Coding the initialization routine.........................................................................................................451 Defining what your