z/OS Version 2 Release 3 TSO/E Programming Guide IBM SA32-0981-30 Note Before using this information and the product it supports, read the information in “Notices” on page 137. 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....................................................................................................... ix List of Tables........................................................................................................ xi About this document...........................................................................................xiii Who should use this document.................................................................................................................xiii How this document is organized............................................................................................................... xiii How to use this document.........................................................................................................................xiii Where to find more information................................................................................................................ xiii How to send your comments to IBM......................................................................xv If you have a technical problem.................................................................................................................xv Summary of changes...........................................................................................xvi Summary of changes for TSO/E for Version 2 Release 3 (V2R3) and its updates................................... xvi Summary of changes for z/OS Version 2 Release 2 (V2R2)..................................................................... xvi z/OS Version 2 Release 1 summary of changes....................................................................................... xvi Part 1. Introduction............................................................................................... 1 Chapter 1. Programming Using TSO/E.........................................................................................................3 What is a REXX Exec?............................................................................................................................. 3 What is a CLIST?..................................................................................................................................... 4 What is a command processor?............................................................................................................. 4 Considerations for Writing REXX Execs, CLISTs and command processors.........................................5 Storing REXX Execs in VLF Storage........................................................................................................6 Controlling REXX Exec Compression................................................................................................6 What is an APPC/MVS Transaction Program?........................................................................................7 What is a Server?.................................................................................................................................... 8 Overview of TSO/E Programming Services............................................................................................ 8 Syntax Notational Conventions..............................................................................................................9 Part 2. Writing a command processor................................................................... 11 Chapter 2. What is a command processor?.............................................................................................. 13 The TSO/E Environment....................................................................................................................... 13 The command processor parameter list (CPPL)............................................................................ 13 Accessing the user profile table without a CPPL.................................................................................14 Command Syntax................................................................................................................................. 15 What is a Subcommand Processor?.....................................................................................................16 Chapter 3. Writing a command processor.................................................................................................17 Chapter 4. Validating command operands................................................................................................19 Using the parse service routine........................................................................................................... 19 Checking positional operands for logical errors............................................................................ 20 Checking unidentified keyword operands......................................................................................20 Using the prompt mode HELP........................................................................................................ 21 A sample command processor............................................................................................................ 22 Chapter 5. Communicating with the Terminal User..................................................................................27 Issuing Messages................................................................................................................................. 27 Message Levels............................................................................................................................... 27 iii Using the I/O Service Routines to Handle Messages.....................................................................27 Using the TSO/E Message Issuer Routine (IKJEFF02).................................................................. 28 Using generalized routines for issuing messages.......................................................................... 28 Performing Terminal I/O...................................................................................................................... 28 Changing Your Command Processor's Source of Input...................................................................... 29 Writing a Full-Screen command processor......................................................................................... 29 Set Full-Screen Mode On................................................................................................................ 31 Give Control to the command processor........................................................................................31 Write to and Get Information from the Terminal........................................................................... 31 Exiting and Reentering Full-Screen Mode......................................................................................32 Full-Screen command processor Termination...............................................................................33 Examples of Full-Screen command processor Operation............................................................. 33 Chapter 6. Passing Control to Subcommand Processors......................................................................... 39 Step 1. Issuing a Mode Message and Retrieving an Input Line.......................................................... 39 Step 2. Validating the Subcommand Name.........................................................................................39 Step 3. Passing control to the subcommand processor......................................................................40 Writing a subcommand processor..................................................................................................40 Step 4. Releasing the Subcommand Processor...................................................................................40 Chapter 7. Processing Abnormal Terminations........................................................................................ 41 Error handling routines.........................................................................................................................41 ESTAE and ESTAI Exit Routines......................................................................................................41 When are Error Handling Routines Needed?....................................................................................... 41 Guidelines for Writing ESTAE and ESTAI Exit Routines.......................................................................42 Linkage Considerations...................................................................................................................43 Chapter 8. Processing Attention Interruptions.........................................................................................45 Responding to Attention Interruptions................................................................................................45 How Attention Interruptions are Processed........................................................................................45