Practical Usage of ISPF Dialog Manager

Springer London Berlin Heidelberg New York Barcelona Budapest Hong Kong Milan Paris Santa Clara Singapore Tokyo

Anthony S. Rudd

Practical Usage of ISPF Dialog Manager With 62 Figures

, Springer

Anthony S. Rudd, MS(Hons) DateveG Paumgartnerstrasse 6-14 D-90426 Nuremberg, GERMANY

ISBN-13:978-3-540-19950-2

British Library Cataloguing in Publication Data Rudd, Anthony S.

Practical usage ofISPF Dialog Manager. - 2nd ed. l.ISPF Dialog Manager (Computer program) 2.Computer programs I.Title 005.3'29

ISBN-13:978-3-540-19950-2 e-ISBN-13:978-1-4471-3040-6 DOl: 10.1007/978-1-4471-3040-6

Library of Congress Cataloging-in-Publication Data A catalog record for this book is available from the Library of Congress

Apart from any fair dealing for the purposes of research or private study, or criticism or review, as permitted under the Copyright, Designs and Patents Act 1988, this publication may only be reproduced, stored or transmitted, in any form or by any means, with the prior permission in writing of the publishers, or in the case of reprographic reproduction in accordance with the terms of licences issued by the Copyright Licensing Agency. Enquiries concerning reproduction outside those terms should be sent to the publishers.

© Springer-Verlag London Limited 1996

The use of registered names, trademarks etc. in this publication does not imply, even in the absence of a specific statement, that such names are exempt from the relevant laws and regulations and therefore free for general use.

The publisher makes no representation, express or implied, with regard to the accuracy of the information contained in this book and cannot accept any legal responsibility or liability for any errors or omissions that may be made.

Typesetting: camera ready by author

34/3830-543210 Printed on acid-free paper

Preface

The title of this book "PRACTICAL USAGE OF ISPF DIALOG MANAGER" reveals the purpose I had in writing it: a concise, complete, source of information necessary for the development of applications using IBM's ISPF Dialog Manager package. Furthermore, this book is hopefully more than a mere reference; it contains tips and notes I and my colleagues found out the hard way. I have tried to present this practical information in such a form that it is easy to find and use. I hope this will enable readers to spend more productive time developing, rather than trying to find out why something works in a particular way.

The original book was based on courses I have conducted for ISPF Dialog Manager over a number of years, and many of the students' criticisms and comments have been incorporated into the examples and explanations. This second edition has been extended to cover windowing, the CUA (Common User Access) standard as applied to ISPF, Library Management, and ISPF Client/Server. Because a full discussion of DTL (Dialog Tag Language) would exceed the scope of this book, it is not covered in detail. Similarly, some specialised features (such as Double-Byte Character Set) are not covered.

To reflect the change of emphasis in the procedural language, the CLIST chapter has been removed, and many examples illustrate the use of REXX.

vi PREFACE

And who should read this book? Both beginners and experts. Beginners are lead through the steps required to develop dialogue applications; complete worked examples, large enough to be practical but devoid of superfluous detail, enable the Dialog Manager novice to see what is necessary to write a simple application. Experts have a compact reference for ISPF Dialog Manager.

Table of Contents

Preface .............................................................................. v

1. Introduction 1.1 Historical development ................................................. 1 1.2 General application area ................................................ 2 1.3 Comparison with other dialogue systems ............................ 3 1.4 The future of ISPF ........................................................ 4

2. General Concepts 2.1 Definition of data processing .......................................... 5 2.2 Definition of dialogue ................................................... 6 2.3 Dialogue components ................................................... 6 2.4 Introduction to DTL ...................................................... 9

3. Invocation 3.1 Introduction .............................................................. 10 3.2 Invocation services ..................................................... 10

3.2.1 ISPSTART - Initiate ISPF environment and invoke function ........ ll 3.2.2 SELECT - Invoke function ............................................... 14

3.3 Miscellaneous environmental services ............................... 17 3.3.1 CONTROL - Set processing modes ....................................... 17 3.3.2 LIBDEF - Define application libraries ................................. 19 3.3.3 LIST - Write data lines to ISPF list dataset.. ......................... 23 3.3.4 LOG - Write a message to the ISPF log dataset ....................... 24 3.3.5 QLlBDEF - Query LIBDEF information .................................. 25

3.4 ISPF service invocation ................................................. 26 3.4.1 Error message variables ................................................ 26

viii TABLE OF CONTENTS

3.5 3.5.1 3.5.2

Batch invocation ........................................................ 27 Panel input in batch .................................................... 27 Sample batch JCL ........................................................ 27

4. Command Procedures 4.1 Introduction .............................................................. 28 4.2 CLIST features ............................................................ 29

4.2.1 CLIST syntax summary ................................................. 29 4.3 REXX features ............................................................ 29

4.3.1 REXX syntax summary ................................................. 30 4.4 TSO commands .......................................................... 31

4.4.1 ALLOC - Allocate dataset or file ........................................ 31 4.4.2 CALL - Execute program ................................................ 32 4.4.3 EXEC - Execute command procedure .................................. 32 4.4.4 FREE - Release dataset or file .......................................... 32 4.4.5 SUBMIT - Submit job control statements for batch execution ...... 33

4.5 Command invocation ................................................... 33 4.5.1 CLIST command invocation ............................................ 33 4.5.2 REXX command invocation ............................................ 33

5. Panels 5.1 5.2

5.3

5.2.1 5.2.2 5.2.3 5.2.4 5.2.5 5.2.6

Introduction .............................................................. 35 Panel definition ......................................................... 36 ADD POP - Pop-up panel display ....................................... 38 DISPLAY - Data input panel ........................................... 39 REMPOP - Revoke pop-up panel display ............................ .42 SELECT - Selection panel .............................................. 42 TBDISPL - Table display panel ...................................... .46 Help panel ............................................................... 49 Preprocessed panels .................................................... 50

6. Variable Services 6.1 6.2 6.3

6.4

6.3.1 6.3.2 6.3.3 6.3.4 6.3.5

6.5 6.5.1 6.5.2 6.5.3

6.6 6.6.1 6.6.2 6.6.3 6.6.4

Introduction .............................................................. 53 Syntax .................................................................... 54 Variable pools ........................................................... 54 Function pool ............................................................ 54 Shared pool .............................................................. 54 Profile pool .............................................................. 54 Read-only profile pool ................................................. 55 Command procedure pool ............................................. 56 Access to variables and pools ......................................... 56 Variable services ........................................................ 57 VERASE - Remove variables from shared or profile pool ........... 57 VGET - Get variable from a pool or profile .......................... 58 VPUT - Put variable into a pool or profile ............................ 59 System variables ........................................................ 60 General variables ....................................................... 61 Time and date variables ................................................ 61 Terminal functions and PF key variables ........................... 62 Scrolling variables ...................................................... 62

6.6.5 6.6.6 6.6.7 6.6.8 6.6.9 6.6.10 6.6.11

TABLE OF CONTENTS ix

TBO! SPL service variables ............................................... 63 Dialogue error variables ............................................... 63 Control variables in selection panels ................................. 63 Control variables used in help panels ................................ 63 List service variables ................................................... 64 List and log dataset variables ......................................... 64 System variables as panel control variables ......................... 64

7. Message Services 7. 1 Introduction .............................................................. 65 7.2 Form of message ........................................................ 65

7.2.1 Variable substitution ................................................... 67 7.3 Message processing ..................................................... 68 7.4 Message services ........................................................ 69

7.4 .1 GETMSG - Get a message ................................................. 69 7.4.2 LOG - Write a message to the log data set.. .......................... 71 7.4.3 SETMSG - Set a message ................................................. 71

7.5 Symbolic parameters ................................................... 72 7.6 Invocation of messages ................................................ 73

8. Panel Processing 8. 1 Introduction .............................................................. 74 8.2 Hardware characteristics ............................................... 74 8.3 Form of panel ........................................................... 76

8.3.1 Panel section ............................................................. 76 8.3.2 Attribute section ........................................................ 76 8.3.3 Action Bar Choice ( )ABC) section ................................... 85 8.3.4 Action Bar Initialisation ( )ABC! NIT) section ....................... 88 8.3.5 Action Bar Processing ( )ABCPROC) section ......................... 88 8.3.6 Body ( )BOOY) section ................................................. 88 8.3.7 Model ( )BOOY) section ................................................ 92 8.3.8 Area ( )AREA) section .................................................. 93 8.3.9 Initialisation section .................................................... 94 8.3.10 Reinitialisation section ................................................. 94 8.3.11 Processing section ...................................................... 94 8.3.12 Point-And-Shoot ( )PNS) section ..................................... 95 8.3.13 Field-Level ( )HELP) section .......................................... 96 8.3.14 End ( )ENo)section .................................................... 98

8.4 Panel statements ......................................................... 98 8.4.1 Assignment statement (=) .............................................. 98 8.4.2 EX! T statement ........................................................... 99 8.4.3 GOTO statement ........................................................... 99 8.4.4 ! F (ELSE) statement.. .................................................. 100 8.4.5 PANEXIT (panel exit) statement ....................................... 102 8.4.6 REFRESH statement ..................................................... 103 8.4.7 TOG (toggle) statement ................................................ 103 8.4.8 VEOIT (variable edit) statement ...................................... 104 8.4.9 VER (verification) statement .......................................... 106 8.4.10 VGET statement ........................................................ 112 8.4. 11 VPUT statement ............................ . .. . .. .. .. .. .. .. .. . .. .. .. ... 112

x TABLE OF CONTENTS

8.5 8.5.1 8.5.2 8.5.3 8.5.4

8.6 8.6.1 8.6.2 8.6.3 8.6.4 8.6.5 8.6.6 8.6.7 8.6.8 8.6.9 8.6.10 8.6.11 8.6.12 8.6.13

8.7 8.7.1 8.7.2 8.7.3

8.8 8.8.1

8.9 8.9.1 8.9.2

8.10 8.11

8.11.1 8.11.2

8.12 8.13 8.14 8.15 8.16

8.16.1 8.16.2 8.16.3 8.16.4 8.16.5 8.16.6 8.16.7 8.16.8 8.16.9 8.16.10 8.16.11 8.16.12

Panel functions ........................................................ 113 LVLINE function ........................................................ 113 PFK function ............................................................ 114 TRANS function ......................................................... 114 TRUNC function ......................................................... 115 Panel control variables............................................... 116 • ALARM - Set alarm..................................................... 117 .ATTR - Set field attribute ............................................ 117 .ATTRCHAR - Set attribute character .................................. 118 .AUTOSEL - Set auto selection status ................................. 118 • CSRPOS - Set cursor position within field ......................... 118 • CSRROW - Set cursor at table row ................................... 118 • CURSOR - Set cursor at field ......................................... 119 .HELP - Specify help panel ........................................... 119 .MSG - Specify message identifier ................................... 119 .PFK - Obtain PF key ................................................. 120 .RESP - Obtain response .............................................. 120 • TRAI L - TRUNC remainder ............................................. 120 .ZVARS - Placeholder .................................................. 121 Dynamic area .......................................................... 122 Format of a dynamic area ........................................... 122 Dynamic area definition ............................................. 123 Shadow variable ....................................................... 126 Use of dynamic areas ................................................. 126 Scrolling ................................................................ 128 Graphic areas .......................................................... 129 Format of a graphic area ............................................. 130 Graphic area definition ............................................... 130 Use of graphic areas .................................................. 131 Scrollable area ......................................................... 131 Format of a scrollable area .......................................... 132 Definition of a scrollable area ..................................... 1~2 Use of scrollable areas ............................................... 133 Panel area information ............................................ '" 134 Keylists ................................................................. 135 Processing sequence in panels ...................................... 136 Special panel processing ............................................. 137 Panel error processing ............................................... 138 Extended alphabetic validation ..................................... 138 Fields containing mixed data ......................... , .............. 138 Date validation ........................................................ 139 Validation of number of data fields... . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 140 Arithmetic processing................... . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 141 Extended processing.......... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 141 Cursor positioning .................................................... 142 Comprehensive validation ........................................... 142 Dynamic area scrolling .............................................. 143 Conditional setting of message variables ........................ " 144 Mixed Panel Processing Elements .................................. 145

TABLE OF CONTENTS xi

9. Table Services 9.1 9.2 9.3 9.4

9.4.1 9.4.2 9.4.3 9.4.4 9.4.5 9.4.6 9.4.7 9.4.8 9.4.9 9.4.10 9.4.11 9.4.12 9.4.13 9.4.14 9.4.15 9.4.16 9.4.17 9.4.18 9.4.19 9.4.20 9.4.21 9.4.22

General form of table ................................................ 147 Table input/output .................................................... 148 Use of tables ........................................................... 149 Table operations ...................................................... 149 TBADD - Add a row to a table ......................................... 151 TBBOTTOM - Set row pointer at end of table ........................ , 152 TBCLOSE - Close and save table ...................................... 153 TBCREATE - Create a new table ....................................... 154 TBDElETE - Delete a row from a table ............................... 156 TBDISPL - Display table contents .................................... 156 TBEND - Close table without saving ................................. 162 TBERASE - Delete table ................................................ 163 TBEX I ST - Determine whether table row exists.................... 164 TBGET - Retrieve table row ........................................... 164 TBMOO - Unconditional update of table row ........................ 165 TBOPEN - Open a table for processing ............................... 166 TBPUT - Conditional update oftable row ........................... 168 TBQUERY - Obtain table information ................................. 169 TBSARG - Set search argument.. ........................ , ............. 170 TBSAVE - Save table .................................................... 171 TBSCAN - Perform table search ....................................... 173 TBSKI P - Move row pointer .......................................... 175 TBSORT - Sort table .................................................... 176 TBSTATS - Retrieve table statistics ................................... 177 TBTOP - Set row pointer at top of table ............................. 180 TBVCLEAR - Clear table variables ..................................... 180

10. Table Applications 10.1 Introduction ............................................................ 182 10.2 Example ................................................................ 182 10.3 Table creation ......................................................... 183 10.4 Input of data into the table .......................................... 184 10.5 Display of table records ............................................. 185 10.6 Update of selected table records .................................... 186 10.7 Explicit row positioning ............................................. 187 10.8 Searching on data fields .............................................. 187 10.9 Termination ............................................................ 188 10.10 Complete CLIST •...........•...•.....•................................ 189 10.11 Equivalent processing for non-keyed table ....................... 190

11. File Tailoring Services 11.1 General form of skeleton ............................................ 192 11. 2 File tailoring operations ............................................. 193

11.2.1 FTCLOSE - Terminate file tailoring ................................... 193 11.2.2 FTERASE - Delete member from output library .................... 194 11.2.3 FTlNCL - Include skeleton for processing .......................... 195 11.2.4 FTOPEN - Open file tailoring processing ............................ 195

xii TABLE OF CONTENTS

11.3 11.3.1 11.3.2 11.3.3 11.3.4 11.3.5 11.3.& 11.3.7 11.3.8 11.3.9 11.3.10

11.4 11.5 11.6

Control statements.................................................... 196 )BLANK - Insert blank line ............................................ 197 )CM - Comment ........................................................ 197 )DEFAULT - Default delimiters ........................................ 198 )DOT - Do-table ........................................................ 198 )ENDDOT - End do-table ............................................ '" 199 )ENDSEL - End selection ............................................... 199 )1M - Imbed skeleton .................................................. 199 )SEL - Select. ........................................................... 200 )SET - Assignment .................................................... 202 )TB - Set tab stops ..................................................... 203 Control delimiters .................................................... 204 Data record ............................................................ 206 Symbolic parameters ................................................. 207

12. File Tailoring Applications 12.1 Introduction ............................................................ 208 12.2 Example ................................................................ 208 12.3 Worked example ...................................................... 209

13. Command Table 13.1 introduction ............................................................ 213 13.2 Command hierarchy .................................................. 213 13.3 Command table format. .............................................. 214

13.3.1 ZCTVERB - Verb (command) .......................................... 214 13.3.2 ZCTTRUNC - Truncation length ........................................ 214 13.3.3 ZCTACT - Action ........................................................ 215 13.3.4 ZCTDESC - Description ................................................. 218 13.3.5 Example ................................................................ 219

13 .4 I SPCMDS - Default command table ................................... 219 13.5 Program function keys ............................................... 219

13.5.1 Keylists ................................................................. 221

14. Program Environment 14.1 Introduction ............................................................ 223 14.2 ISPF Program interfaces .............................................. 223

14.2.1 ISPEXEC call interface ................................................. 224 14.2.2 ISPLINK call interface ................................................. 224 14.2.3 Calls which return values indirectly ............................... 224

14.3 Program invocation ................................................... 225 14.4 Program calls .......................................................... 225 14.5 Linkage to services ................................................... 225

14.5.1 Invoked PLII program ................................................ 226 14.5.2 Invoked COBOL program ............................................. 226 14.5.3 Invoked Assembler program ........................................ 226 14.5.4 Invoked C/370 program ............................................... 227

14.6 14.6.1 14.6.2 14.6.3 14.6.4

14.7 14.7.1 14.7.2 14.7.3 14.7.4 14.7.5 14.7.6 14.7.7

14.8 14.9

14.9.1 14.9.2 14.9.3 14.9.4 14.9.5

14.9.6 14.10 14.11

14.11.1 14.11.2 14.11.3 14.11.4

14.12 14.12.1

TABLE OF CONTENTS xiii

Linkage to services ................................................... 227 PLII program invocation .............................................. 227 COBOL program invocation .......................................... 228 Assembler program invocation ..................................... 228 C/370 program invocation ............................................ 228 Program ISPF parameters ............................................ 228 Name ................................................................... 229 Service name .......................................................... 229 Keyword ............................................................... 229 Name list string ....................................................... 230 Name list structure ................................................... 230 Numeric value ......................................................... 230 Dataset list ............................................................. 230 Linkage Editor parameters .......................................... 231 Program variable services ........................................... 231 VCOpy - Copy ISPF variables to program variables ................ 232 VDEFINE - Make ISPF variables available as program variables. 234 VDELETE - Remove availability of ISPF variables .................. 240 VMASK - Specify mask processing .................................... 241 VREPLACE - Replace function pool variables with program variables ................................................................ 243 VRESET - Remove variables from defined function pool ......... 245 Panel exit. .............................................................. 245 Program examples .................................................... 247 Sample PLII program ................................................. 248 Sample COBOL program .............................................. 248 Sample Assembler program ......................................... 249 Sample C/370 program ................................................ 250 Sample panel exit ..................................................... 251 Generalised panel exit ................................................ 253

15. Help Mode 15.1 Introduction ............................................................ 257 15.2 Help panel ............................................................. 258 15.3 Standard help panel.. ................................................. 259 15.4 Table of contents ...................................................... 259 15.5 Index .................................................................... 260 15.6 Help panel hierarchy ................................................. 261 15.7 Field-help .............................................................. 262 15.8 Reference phrase ...................................................... 263 15.9 Definition of help panels ............................................ 263

15.9.1 Dynamically formatted help panels ................................ 263 15.10 Example ................................................................ 265

16. Miscellaneous Display Services 16.1 Introduction ............................................................ 269 16.2 BRIF - Browse interface ............................................ 270

16.2.1 Read routine ........................................................... 271 16.2.2 Command routine ..................................................... 271 16.2.3 Example ................................................................ 272

xiv TABLE OF CONTENTS

16.3 16.4

16.4.1 16.4.2 16.4.3 16.4.4

16.5 16.6 16.7

BROWSE - Browse a dataset or library member ..................... 273 EDI F - Edit interface ................................................ 274 Read routine ........................................................... 276 Write routine .......................................................... 277 Command routine ..................................................... 278 Example ................................................................ 278 EDIREC - Initialise edit recovery ................................... 280 ED IT - Edit a dataset or library member ........................... 280 VIEW - View a dataset or library member .......................... 282

17. Library Management 17.1 Introduction ............................................................ 285

17.1.1 Service identifier ...................................................... 285 17.1.2 Error handling ......................................................... 286

17.2 Library Management services ....................................... 286 17.2.1 LMCLOSE - Close dataset ............................................. 287 17.2.2 LMCOMP - Compress a library ......................................... 287 17.2.3 LMCOPY - Copy library members ..................................... 288 17.2.4 LMDDISP - Dataset display ............................................ 290 17.2.5 LMDFREE - Free a dataset-list ......................................... 291 17.2.6 LMDINIT - Initialise a dataset list.. ................................... 291 17.2.7 LMDLlST - List a dataset. .............................................. 292 17.2.8 LMERASE - Erase (delete) a dataset ................................... 294 17.2.9 LMFREE - Free a dataset association ................................. 295 17.2.10 LMGET - Read a logical record ........................................ 296 17.2.11 LMI N IT - Initialise a dataid for a dataset. ........................... 297 17.2.12 LMMADD - Add member ................................................ 300 17.2.13 LMMDEL - Delete a member ..................... ; ...................... 301 17.2.14 LMMDISP - Member list service ....................................... 301 17.2.15 LMMFIND - Find member ............................................... 306 17.2.16 LMMLI ST - List library members ..................................... 308 17.2.17 LMMOVE - Move library members .................................... 311 17.2.18 LMMREN - Rename member ............................................ 312 17.2.19 LMMREP - Replace member ............................................ 313 17.2.20 LMMSTATS - Set member statistics .................................... 314 17.2.21 LMOPEN - Open a dataset .............................................. 316 17.2.22 LMPR I NT - Print a dataset or member ................................ 318 17.2.23 LMPUT - Write a logical record ....................................... 319 17.2.24 LMQUERY - Retrieve dataset information ............................. 320 17.2.25 LMRENAME - Rename a dataset. ........................................ 322

17.3 Program invocation example ........................................ 323 17.3.1 Invocation forms ...................................................... 324 17.3.2 Data type for program invocation .................................. 324 17.3.3 Sample program ....................................................... 324

17.4 Worked example ...................................................... 325

18. DTL Example 18.1 Introduction ............................................................ 329 18.2 GML definition ......................................................... 330 18.3 Generated display panels ............................................ 332

TABLE OF CONTENTS xv

18.4 Generated help panels ................................................ 333 18.5 Generated messages .................................................. 334 18.6 Generated key list ..................................................... 334 18.7 Generated command table ........................................... 335 18.8 GETDATE coded procedure ............................................. 335 18.9 Coded procedures ..................................................... 336

19. Graphical User Interface 19.1 Introduction ............................................................ 338 19.2 Mainframe-workstation mapping ................................... 338

19.2.1 Action bars ............................................................. 339 19.2.2 Pop-up windows ...................................................... 339 19.2.3 Pop-up messages ...................................................... 339 19.2.4 Point -and-shoot fields ................................................ 340 19.2.5 Push buttons ........................................................... 340 19.2.6 Multi-selection fields (checkboxes) ................................ 341

19.3 GUI invocation ......................................................... 341 19.4 . GUI restrictions ........................................................ 341 19.5 Example ................................................................ 342

20. Test Facilities 20.1 Introduction ............................................................ 353 20.2 Test facility invocation ............................................... 353 20.3 Facilities ............................................................... 354

20.3.1 Option 1 - Invoke function .......................................... 354 20.3.2 Option 2 - Display panel ............................................ 355 20.3.3 Option 3 - Display/modify variable information ................. 356 20.3.4 Option 4 - Display/modify table information .................... 357 20.3.5 Option 5 - Browse ISPF log .......................................... 359 20.3.6 Option 6 - Invoke ISPF service ...................................... 360 20.3.7 Option 7 - Specify trace options .................................... 360 20.3.8 Option 8 - Specify breakpoints ..................................... 361

20.4 Invocation of ISPF from TSO TEST ................................... 362

Appendix A. Syntax ................................................................. 364 Appendix B. Glossary ............................................................... 368

Index .................................................................................... 373