IMS Version 11 -...

IMSVersion 11

Application Programming

SC19-2428-01

NoteBefore using this information and the product that it supports, be sure to read the general information under Notices onpage 697.

This edition applies to IMS Version 11 (program number 5635-A02) and to all subsequent releases and modificationsuntil otherwise indicated in new editions.

Copyright IBM Corporation 1974, 2010.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this information . . . . . . . . ixPrerequisite knowledge . . . . . . . . . . ixIMS function names used in this information . . . ixHow to read syntax diagrams . . . . . . . . xAccessibility features for IMS Version 11 . . . . . xiHow to send your comments . . . . . . . . xii

Changes to the IMS library . . . . . . xiii

Part 1. Application programmingdesign . . . . . . . . . . . . . . . 1

Chapter 1. Designing an application:Introductory concepts. . . . . . . . . 3Storing and processing information in a database . . 3

Database hierarchy examples . . . . . . . . 5Your program's view of the data . . . . . . 10Processing a database record . . . . . . . 12

Tasks for developing an application . . . . . . 13

Chapter 2. Designing an application:Data and local views. . . . . . . . . 15An overview of application design . . . . . . 15Identifying application data . . . . . . . . . 17

Listing data elements . . . . . . . . . . 17Naming data elements. . . . . . . . . . 19Documenting application data . . . . . . . 20

Designing a local view . . . . . . . . . . 22Analyzing data relationships . . . . . . . 22Local view examples . . . . . . . . . . 29

Chapter 3. Analyzing IMS applicationprocessing requirements . . . . . . . 35Defining IMS application requirements . . . . . 35Accessing databases with your IMS applicationprogram . . . . . . . . . . . . . . . 36Accessing data: the types of programs you can writefor your IMS application . . . . . . . . . . 38

DB batch processing . . . . . . . . . . 39TM batch processing . . . . . . . . . . 40Processing messages: Message ProcessingPrograms . . . . . . . . . . . . . . 40Processing messages: IMS Fast Path Programs . . 41Batch message processing: BMPs . . . . . . 42Java message processing: JMPs . . . . . . . 45Java batch processing: JBPs . . . . . . . . 45

IMS programming integrity and recoveryconsiderations . . . . . . . . . . . . . 46

How IMS protects data integrity: commit points 46Planning for program recovery: checkpoint andrestart . . . . . . . . . . . . . . . 49Data availability considerations. . . . . . . 53

Use of STAE or ESTAE and SPIE in IMSprograms . . . . . . . . . . . . . . 55

Dynamic allocation for IMS databases . . . . . 56

Chapter 4. Analyzing CICS applicationprocessing requirements . . . . . . . 57Defining CICS application requirements . . . . . 57Accessing databases with your CICS applicationprogram . . . . . . . . . . . . . . . 58Writing a CICS program to access IMS databases . . 60

Writing a CICS online program . . . . . . . 60Using data sharing for your CICS program . . . . 61Scheduling and terminating a PSB (CICS onlineprograms only) . . . . . . . . . . . . . 62Linking and passing control to other programs(CICS online programs only) . . . . . . . . 63How CICS distributed transactions access IMS . . 63Maximizing the performance of your CICS system 63Programming integrity and database recoveryconsiderations for your CICS program . . . . . 64

How IMS protects data integrity for CICS onlineprograms . . . . . . . . . . . . . . 64Recovering databases accessed by batch and BMPprograms . . . . . . . . . . . . . . 65

Data availability considerations for your CICSprogram . . . . . . . . . . . . . . . 69

Unavailability of a database . . . . . . . . 69Unavailability of some data in a database . . . 70The SETS or SETU and ROLS functions . . . . 70

Use of STAE or ESTAE and SPIE in IMS batchprograms . . . . . . . . . . . . . . . 71Dynamic allocation for IMS databases . . . . . 71

Chapter 5. Gathering requirements fordatabase options . . . . . . . . . . 73Analyzing data access . . . . . . . . . . . 73

Direct access . . . . . . . . . . . . . 74Sequential access . . . . . . . . . . . 78Accessing z/OS files through IMS: GSAM . . . 80Accessing IMS data through z/OS: SHSAM andSHISAM . . . . . . . . . . . . . . 80

Understanding how data structure conflicts areresolved . . . . . . . . . . . . . . . 81

Using different fields: field-level sensitivity . . . 81Resolving processing conflicts in a hierarchy:secondary indexing . . . . . . . . . . . 82Creating a new hierarchy: logical relationships . 86

Providing data security . . . . . . . . . . 91Keeping a program from accessing the data: datasensitivity . . . . . . . . . . . . . . 91Preventing a program from updating data:processing options . . . . . . . . . . . 93

Read without integrity. . . . . . . . . . . 95

Copyright IBM Corp. 1974, 2010 iii

||

Chapter 6. Gathering requirements formessage processing options . . . . . 99Identifying online security requirements . . . . . 99Analyzing screen and message formats . . . . . 101

An overview of MFS . . . . . . . . . . 102An overview of basic edit . . . . . . . . 102Editing considerations in your application. . . 102

Gathering requirements for conversationalprocessing . . . . . . . . . . . . . . 103

What happens in a conversation . . . . . . 104Designing a conversation . . . . . . . . 104Important points about the scratchpad area(SPA) . . . . . . . . . . . . . . . 105Recovery considerations in conversations . . . 106

Identifying output message destinations . . . . 107The originating terminal. . . . . . . . . 107To other programs and terminals . . . . . . 107

Chapter 7. Designing an applicationfor APPC . . . . . . . . . . . . . 111Overview of APPC and LU 6.2 . . . . . . . 111Application program types . . . . . . . . . 111Application objectives . . . . . . . . . . 113Conversation type . . . . . . . . . . . . 114Conversation state . . . . . . . . . . . . 115Synchronization level . . . . . . . . . . . 115Introduction to resource recovery . . . . . . . 116Summary of z/OS Resource Recovery Servicessupport . . . . . . . . . . . . . . . 119Distributed sync point . . . . . . . . . . 120Application programming interface for LU type 6.2 121LU 6.2 partner program design . . . . . . . 122

LU 6.2 flow diagrams . . . . . . . . . 122Integrity tables . . . . . . . . . . . . 142DFSAPPC message switch . . . . . . . . 144

Chapter 8. Testing an IMS applicationprogram . . . . . . . . . . . . . 147What you need to test an IMS program . . . . 147Testing DL/I call sequences (DFSDDLT0) beforetesting your IMS program . . . . . . . . . 147Using BTS II to test your IMS program . . . . . 148Tracing DL/I calls with image capture for yourIMS program . . . . . . . . . . . . . 148

Using image capture with DFSDDLT0 . . . . 149Restrictions on using image capture output . . 149Running image capture online. . . . . . . 149Running image capture as a batch job . . . . 150Retrieving image capture data from the log dataset . . . . . . . . . . . . . . . . 150

Requests for monitoring and debugging your IMSprogram . . . . . . . . . . . . . . . 151

Retrieving database statistics: the STAT call . . 151Writing Information to the system log: the LOGrequest . . . . . . . . . . . . . . 165

What to do when your IMS program terminatesabnormally . . . . . . . . . . . . . . 165

Chapter 9. Testing a CICS applicationprogram . . . . . . . . . . . . . 169What you need to test a CICS program. . . . . 169Testing your CICS program. . . . . . . . . 169

Tracing DL/I calls with image capture . . . . 170Requests for monitoring and debugging your CICSprogram . . . . . . . . . . . . . . . 174What to do when your CICS program terminatesabnormally . . . . . . . . . . . . . . 174

Chapter 10. Documenting yourapplication program . . . . . . . . 177Documentation for other programmers . . . . . 177Documentation for end users . . . . . . . . 177

Part 2. Application programmingfor IMS DB . . . . . . . . . . . . 179

Chapter 11. Writing your applicationprograms for IMS DB . . . . . . . . 181Programming guidelines . . . . . . . . . 181Segment search arguments (SSAs) . . . . . . 182

SSA guidelines . . . . . . . . . . . . 185Multiple qualification statements . . . . . . 186SSAs and command codes . . . . . . . . 189

Considerations for coding DL/I calls and dataareas . . . . . . . . . . . . . . . . 190Preparing to run your CICS DL/I call program . . 191Examples of how to code DL/I calls and data areas 191

Coding a batch program in assembler language 192Coding a CICS online program in assemblerlanguage . . . . . . . . . . . . . . 194Coding a batch program in C language. . . . 196Coding a batch program in COBOL . . . . . 198Coding a CICS online program in COBOL. . . 201Coding a program in Java . . . . . . . . 205Coding a batch program in Pascal . . . . . 205Coding a batch program in PL/I . . . . . . 207Coding a CICS online program in PL/I. . . . 210

Chapter 12. Defining applicationprogram elements for IMS DB . . . . 213Formatting DL/I calls for language interfaces . . 213Assembler language application programming . . 213C language application programming . . . . . 215COBOL application programming . . . . . . 218Java application programming for IMS . . . . . 221Pascal application programming . . . . . . . 221Application programming for PL/I . . . . . . 224Specifying the I/O PCB mask . . . . . . . . 226Specifying the DB PCB mask . . . . . . . . 230Specifying the AIB mask . . . . . . . . . 232Specifying the AIB mask for ODBA applications 234Specifying the UIB (CICS online programs only) 237Specifying the I/O areas. . . . . . . . . . 239Formatting segment search arguments (SSAs) . . 240

SSA coding rules . . . . . . . . . . . 240SSA coding formats . . . . . . . . . . 241

iv Application Programming

||

||

||

Data areas in GSAM databases . . . . . . . 245AIBTDLI interface . . . . . . . . . . . . 245Language specific entry points . . . . . . . 246Program communication block (PCB) lists . . . . 249The AERTDLI interface . . . . . . . . . . 251Language environments . . . . . . . . . . 251Special DL/I situations for IMS DB programming 252

Chapter 13. Establishing a DL/Iinterface from COBOL or PL/I . . . . 255

Chapter 14. Current position in thedatabase after each call . . . . . . . 257Current position after successful calls . . . . . 257

Position after retrieval calls . . . . . . . . 259Position after DLET . . . . . . . . . . 259Position after REPL . . . . . . . . . . 261Position after ISRT. . . . . . . . . . . 261

Current position after unsuccessful calls . . . . 263Multiple processing . . . . . . . . . . . 267

Advantages of using multiple positioning . . . 271Multiple DB PCBs . . . . . . . . . . . 274

Chapter 15. Using IMS applicationprogram sync points . . . . . . . . 275Commit process . . . . . . . . . . . . 275Two-phase commit in the synchronization process 276

Unit of recovery . . . . . . . . . . . 278DBCTL single-phase commit . . . . . . . 279

Sync-point log records . . . . . . . . . . 279Sync points with a data-propagation manager . . 280

Chapter 16. Recovering databasesand maintaining database integrity . . 283Issuing checkpoints . . . . . . . . . . . 283Restarting your program from the latest checkpoint 284Maintaining database integrity (IMS batch, BMP,and IMS online regions) . . . . . . . . . . 284

Backing out to a prior commit point: ROLL,ROLB, and ROLS . . . . . . . . . . . 284Backing out to an intermediate backout point:SETS, SETU, and ROLS . . . . . . . . . 288

Reserving segments for the exclusive use of yourprogram . . . . . . . . . . . . . . . 291

Chapter 17. Secondary indexing andlogical relationships . . . . . . . . 293How secondary indexing affects your program . . 293

SSAs with secondary indexes . . . . . . . 293Multiple qualification statements withsecondary indexes . . . . . . . . . . . 294DL/I returns with secondary indexes . . . . 296Status codes for secondary indexes . . . . . 296

Processing segments in logical relationships . . . 297How logical relationships affect yourprogramming . . . . . . . . . . . . 299Status codes for logical relationships . . . . 299

Chapter 18. HALDB selective partitionprocessing . . . . . . . . . . . . 301

Chapter 19. Processing GSAMdatabases . . . . . . . . . . . . . 305Accessing GSAM databases. . . . . . . . . 305

PCB masks for GSAM databases . . . . . . 305Retrieving and inserting GSAM records . . . 308Explicit open and close calls to GSAM . . . . 309

GSAM record formats . . . . . . . . . . 309GSAM I/O areas . . . . . . . . . . . . 310GSAM status codes . . . . . . . . . . . 310Symbolic CHKP and XRST with GSAM . . . . 311GSAM coding considerations . . . . . . . . 311Origin of GSAM data set characteristics . . . . 312

DD statement DISP parameter for GSAM datasets. . . . . . . . . . . . . . . . 313Extended checkpoint restart for GSAM data sets 314Concatenated data sets used by GSAM . . . . 315Specifying GSAM data set attributes. . . . . 315DLI, DBB, and BMP region types and GSAM 316

Chapter 20. Processing Fast Pathdatabases . . . . . . . . . . . . . 319Fast Path database calls . . . . . . . . . . 320Main storage databases (MSDBs) . . . . . . . 321

Restrictions on using calls for MSDBs . . . . 321Data entry databases (DEDBs) . . . . . . . . 322Updating segments: REPL, DLET, ISRT, and FLD 322

Checking the contents of a field: FLD/VERIFY 323Changing the contents of a field:FLD/CHANGE. . . . . . . . . . . . 325Example of using FLD/VERIFY andFLD/CHANGE. . . . . . . . . . . . 326Commit-point processing in MSDBs and DEDBs 327

Processing DEDBs (IMS and CICS with DBCTL) 328Processing DEDBs with subset pointers. . . . 328Retrieving location with the POS call (for DEDBonly) . . . . . . . . . . . . . . . 333Commit-point processing in a DEDB . . . . 336P processing option . . . . . . . . . . 336H processing option . . . . . . . . . . 336

Calls with dependent segments for DEDBs . . . 337DEDB DL/I calls to extract DEDB information . . 338

AL_LEN Call . . . . . . . . . . . . 342DI_LEN Call . . . . . . . . . . . . 343DS_LEN Call . . . . . . . . . . . . 343AREALIST Call. . . . . . . . . . . . 343DEDBINFO Call . . . . . . . . . . . 344DEDSTR Call . . . . . . . . . . . . 344

Fast Path coding considerations . . . . . . . 345

Chapter 21. Writing ODBA applicationprograms . . . . . . . . . . . . . 347General application program flow of ODBAapplication programs . . . . . . . . . . . 347Server program structure . . . . . . . . . 350

DB2 for z/OS stored procedures use of ODBA 351Testing an ODBA application program . . . . . 352

Contents v

||

Tracing DL/I calls with image capture to testyour ODBA program . . . . . . . . . . 353Using image capture with DFSDDLT0 to testyour ODBA program . . . . . . . . . . 354Running image capture online. . . . . . . 354Retrieving image capture data from the log dataset . . . . . . . . . . . . . . . . 355Requests for monitoring and debugging yourODBA program. . . . . . . . . . . . 355What to do when your ODBA programterminates abnormally . . . . . . . . . 356

Chapter 22. Programming with theIMS support for DRDA . . . . . . . 359DDM commands for data operations with the IMSsupport for DRDA . . . . . . . . . . . 360

Part 3. Application programmingfor IMS TM . . . . . . . . . . . . 363

Chapter 23. Defining applicationprogram elements for IMS TM . . . . 365Formatting DL/I calls for language interfaces . . 365Application programming for assembler language 365Application programming for C language . . . . 367Application programming for COBOL . . . . . 371Java application programming for IMS . . . . . 373Application programming for Pascal . . . . . 373Application programming for PL/I . . . . . . 376Relationship of calls to PCB types . . . . . . 378Specifying the I/O PCB mask . . . . . . . . 379Specifying the alternate PCB mask . . . . . . 383Specifying the AIB mask . . . . . . . . . 383Specifying the I/O areas. . . . . . . . . . 385AIBTDLI interface . . . . . . . . . . . . 386Specifying language-specific entry points . . . . 387Program communication block (PCB) lists . . . . 389Language environments . . . . . . . . . . 390Special DL/I situations for IMS TM programming 391

Chapter 24. Message processing withIMS TM . . . . . . . . . . . . . . 395How your program processes messages . . . . 395

Message types . . . . . . . . . . . . 395When a message is processed . . . . . . . 398Results of a message: I/O PCB . . . . . . 400

How IMS TM edits messages . . . . . . . . 400Printing output messages . . . . . . . . 401Using Basic Edit . . . . . . . . . . . 401Using Intersystem Communication Edit . . . 402Using Message Format Service . . . . . . 402Using LU 6.2 User Edit exit routine (optional) 409

Message processing considerations for DB2 . . . 409Sending messages to other terminals and programs 410

Sending messages to other terminals . . . . 411Sending messages to other IMS applicationprograms . . . . . . . . . . . . . . 413How the VTAM I/O facility affects your VTAMterminal . . . . . . . . . . . . . . 415

Communicating with other IMS TM systems usingMultiple Systems Coupling . . . . . . . . . 415

Implications of MSC for program coding . . . 416Receiving messages from other IMS TM systems 416Sending messages to alternate destinations inother IMS TM systems . . . . . . . . . 418

IMS conversational processing. . . . . . . . 419A conversational example . . . . . . . . 419Conversational structure. . . . . . . . . 420Replying to the terminal. . . . . . . . . 424Conversational processing using ROLB, ROLL,and ROLS . . . . . . . . . . . . . 424Passing the conversation to anotherconversational program . . . . . . . . . 425Message switching in APPC conversations . . 428

Processing conversations with APPC . . . . . 429Ending the APPC conversation . . . . . . 430Coding a conversational program . . . . . 430Standard IMS application programs . . . . . 431Modified IMS application programs . . . . . 431CPI-C driven application programs . . . . . 432

Processing conversations with OTMA . . . . . 433Backing out to a prior commit point: ROLL, ROLB,and ROLS calls . . . . . . . . . . . . . 433

Comparison of ROLB, ROLL, and ROLS . . . 434ROLL . . . . . . . . . . . . . . . 434ROLB . . . . . . . . . . . . . . . 435ROLS . . . . . . . . . . . . . . . 436

Backing out to an intermediate backout point:SETS/SETU and ROLS . . . . . . . . . . 437Writing message-driven programs . . . . . . 440Coding DC calls and data areas . . . . . . . 440

Before coding your program . . . . . . . 441MPP code examples . . . . . . . . . . 441Message processing considerations for DB2 . . 448

Chapter 25. IMS Spool API . . . . . . 449Managing the IMS Spool API overall design . . . 449

IMS Spool API design . . . . . . . . . 449Sending data to the JES spool data sets . . . . 450IMS Spool API performance considerations . . 450IMS Spool API application codingconsiderations . . . . . . . . . . . . 451

Understanding parsing errors . . . . . . . . 454Diagnosis examples . . . . . . . . . . 455

Understanding allocation errors . . . . . . . 458Understanding dynamic output for print data sets 458Sample programs using the Spool API . . . . . 459

Chapter 26. IMS Message FormatService . . . . . . . . . . . . . . 463Advantages of using MFS . . . . . . . . . 463MFS control blocks . . . . . . . . . . . 464

MFS examples . . . . . . . . . . . . 465Relationship between MFS control blocks andscreen format . . . . . . . . . . . . 469

Overview of MFS components and operations . . 470MFS Language utility (DFSUPAA0) . . . . . 471MFS Service utility (DFSUTSA0) . . . . . . 472

vi Application Programming

||||||

MFS Device Characteristics Table utility(DFSUTB00) . . . . . . . . . . . . . 472MFS message editor . . . . . . . . . . 473MFS pool manager . . . . . . . . . . 473MFSTEST pool manager . . . . . . . . . 473

Devices and logical units that operate with MFS 473Using distributed presentation management (DPM) 475

Chapter 27. Callout requests forexternal services or data . . . . . . 477Callout request approaches . . . . . . . . . 478OTMA destination descriptors . . . . . . . . 478Resume tpipe protocol . . . . . . . . . . 479Implementing the synchronous callout function 480Implementing the asynchronous callout function 483

Part 4. Application programmingfor EXEC DLI . . . . . . . . . . . 485

Chapter 28. Writing your applicationprograms for EXEC DLI . . . . . . . 487Programming guidelines . . . . . . . . . 487

Coding a program in assembler language . . . 488Coding a program in COBOL . . . . . . . 492Coding a program in PL/I . . . . . . . . 495Coding a program in C . . . . . . . . . 499

Preparing your EXEC DLI program for execution 505Translator, compiler, and binder optionsrequired for EXEC DLI . . . . . . . . . 505

Chapter 29. Defining applicationprogram elements . . . . . . . . . 507Specifying an application interface block (AIB) . . 507Specifying the DL/I interface block (DIB) . . . . 507Defining a key feedback area . . . . . . . . 511Defining I/O areas . . . . . . . . . . . 511

Chapter 30. EXEC DLI commands foran application program . . . . . . . 513PCBs and PSB . . . . . . . . . . . . . 513

Chapter 31. Recovering databasesand maintaining database integrity . . 517Issuing checkpoints in a batch or BMP program 517Restarting your program and checking for position 518Backing out database updates dynamically: theROLL and ROLB commands . . . . . . . . 518Using intermediate backout points: the SETS andROLS commands . . . . . . . . . . . . 518

Chapter 32. Processing Fast Pathdatabases . . . . . . . . . . . . . 521Processing DEDBs with subset pointers. . . . . 521

Preparing to use subset pointers . . . . . . 523Designating subset pointers . . . . . . . 524Subset pointer options . . . . . . . . . 524Subset pointer status codes . . . . . . . . 531

The POS command . . . . . . . . . . . 532Locating a specific sequential dependentsegment . . . . . . . . . . . . . . 532Locating the last inserted sequential dependentsegment . . . . . . . . . . . . . . 533Identifying free space with the POS command 533The P processing option . . . . . . . . . 534

Chapter 33. Comparingcommand-level and call-levelprograms . . . . . . . . . . . . . 535DL/I calls for IMS and CICS . . . . . . . . 535Comparing EXEC DLI commands and DL/I calls 535Comparing command codes and options . . . . 537

Chapter 34. Data availabilityenhancements . . . . . . . . . . . 539

Part 5. Java applicationdevelopment for IMS . . . . . . . 541

Chapter 35. IMS solutions for Javadevelopment overview . . . . . . . 543

Chapter 36. Programming with theIMS Universal drivers . . . . . . . . 547IMS Universal drivers overview . . . . . . . 547

Distributed and local connectivity with the IMSUniversal drivers . . . . . . . . . . . 548Comparison of IMS Universal driversprogramming approaches for accessing IMS . . 551Generating the runtime Java metadata class . . 553Hospital database example . . . . . . . . 554

Programming using the IMS Universal DB resourceadapter . . . . . . . . . . . . . . . 557

Overview of the IMS Universal DB resourceadapter . . . . . . . . . . . . . . 557Transaction types and programming interfacessupported by the IMS Universal DB resourceadapter . . . . . . . . . . . . . . 558Connecting to IMS with the IMS Universal DBresource adapter . . . . . . . . . . . 559Sample EJB application using the IMS UniversalDB resource adapter CCI programming interface 564Accessing IMS data with the DLIInteractionSpecclass . . . . . . . . . . . . . . . 566Accessing IMS data with theSQLInteractionSpec class . . . . . . . . 570Accessing IMS data with the IMS UniversalJCA/JDBC driver . . . . . . . . . . . 573

Programming with the IMS Universal JDBC driver 575Supported drivers for JDBC . . . . . . . 576Connecting to IMS using the IMS UniversalJDBC driver . . . . . . . . . . . . . 576Sample application for the IMS Universal JDBCdriver . . . . . . . . . . . . . . . 582Writing SQL queries to access an IMS databasewith the IMS Universal JDBC driver. . . . . 584

Contents vii

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

|||

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

Data transformation support for JDBC . . . . 596Programming with the IMS Universal DL/I driver 602

Basic steps in writing a IMS Universal DL/Idriver application . . . . . . . . . . . 602Java packages for IMS Universal DL/I driversupport . . . . . . . . . . . . . . 603Connecting to an IMS database by using theIMS Universal DL/I driver . . . . . . . . 603IMS Universal DL/I driver interfaces forexecuting DL/I operations . . . . . . . . 605Inspecting the PCB status code and relatedinformation using the com.ibm.ims.dli.AIBinterface . . . . . . . . . . . . . . 621Committing or rolling back DL/I transactions 623

Configuring the IMS Universal drivers for SSLsupport . . . . . . . . . . . . . . . 625

Configuring the IMS Universal DB resourceadapter for SSL support in a container-managedenvironment. . . . . . . . . . . . . 625Configuring IMS Universal drivers for SSLsupport in a stand-alone environment . . . . 626

Tracing IMS Universal drivers applications . . . 626

Chapter 37. Programming for IMSJava dependent regions. . . . . . . 629Overview of the IMS Java dependent regions. . . 629Programming with the IMS Java dependent regionresource adapter . . . . . . . . . . . . 630

Developing JMP applications with the IMS Javadependent region resource adapter . . . . . 631Developing JBP applications with the IMS Javadependent region resource adapter . . . . . 641Program switching in JMP and JBP applications 649

IBM Enterprise COBOL for z/OS interoperabilitywith JMP and JBP applications . . . . . . . 652

IBM Enterprise COBOL for z/OS backendapplications in a JMP or JBP region . . . . . 653IBM Enterprise COBOL for z/OS frontendapplications in a JMP or JBP region . . . . . 653

Accessing DB2 for z/OS databases from JMP orJBP applications . . . . . . . . . . . . 654Issuing synchronous callout requests from a Javadependent region . . . . . . . . . . . . 655

Chapter 38. Programming with theclassic Java APIs for IMS . . . . . . 657Programming enterprise Java applications withclassic Java APIs for IMS resource adapters . . . 657

Accessing IMS data from WebSphereApplication Server for z/OS with the classicJava APIs for IMS . . . . . . . . . . . 657

Bean-managed EJB programming model . . . 658Container-managed EJB programming model 660Servlet programming model . . . . . . . 660Requirements for WebSphere Application Serverfor z/OS with the classic Java APIs for IMS . . 661Deployment descriptor requirements for theclassic Java APIs for IMS . . . . . . . . 662

Programming Java applications in DB2 for z/OSstored procedures with the classic Java APIs forIMS . . . . . . . . . . . . . . . . 662

Accessing IMS data from DB2 for z/OS storedprocedures using the classic Java APIs for IMS . 663DB2 for z/OS stored procedures programmingmodel with the classic Java APIs for IMS . . . 663

Programming Java applications for CICS with theclassic Java APIs for IMS . . . . . . . . . 664

Accessing IMS data from CICS with the classicJava APIs for IMS . . . . . . . . . . . 664CICS programming model with the classic JavaAPIs for IMS . . . . . . . . . . . . 665

Programming with the IMS classic JDBC driver 666Sample PSB, DBD and DLIModel IMS Javareport . . . . . . . . . . . . . . . 666Data transformation support for JDBC . . . . 668Connections to IMS databases . . . . . . . 674JDBC interfaces supported by the IMS classicJDBC driver . . . . . . . . . . . . . 674SQL keywords and extensions for the IMSclassic JDBC driver . . . . . . . . . . 676Sample application that uses the IMS classicJDBC driver . . . . . . . . . . . . . 687

Problem determination for Java applications . . . 688Exceptions thrown from IMS DL/I calls . . . 688XML tracing for the classic Java APIs for IMSfor IMS . . . . . . . . . . . . . . 690

Part 6. Appendixes . . . . . . . . 695

Notices . . . . . . . . . . . . . . 697Programming interface information . . . . . . 699Trademarks . . . . . . . . . . . . . . 699

Bibliography. . . . . . . . . . . . 701

Index . . . . . . . . . . . . . . . 703

viii Application Programming

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

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

|||

|||

About this information

These topics provide guidance information for writing application programs thataccess IMS databases or IMS transactions. The topics describe how to gather andanalyze program requirements, and how to develop and debug IMS applicationprograms. They also describe how to use different programming languages to issueDL/I calls, and include information about the IMS solutions for Java

development. They also describe how to use different programming languages toissue EXEC DL/I calls. Application programming interface (API) information is inIMS Version 11 Application Programming APIs.

This information is available as part of the Information Management Software forz/OS Solutions Information Center at http://publib.boulder.ibm.com/infocenter/imzic. A PDF version of this information is available in the information center.

Prerequisite knowledge

This information is a guide to IMS application programming for any of thefollowing environments:v IMS Database Manager (IMS DB), including IMS Database Control (DBCTL)v IMS Transaction Manager (IMS TM)v CICS EXEC DLIv WebSphere Application Server for z/OSv WebSphere Application Server for distributed platformsv Java dependent regions (JMP and JBP)v Any environment for stand-alone Java application development

This book provides guidance information for writing application programs thataccess IMS databases or process IMS messages. It also describes how to usedifferent programming languages to make DL/I, EXEC DLI, or JDBC calls thatinteract with IMS. API (application programming interface) information is in IMSVersion 11 Application Programming APIs.

You can gain an understanding of basic IMS concepts by reading An Introduction toIMS, an IBM Press publication written by Dean H. Meltz, Rick Long, MarkHarrington, Robert Hain, and Geoff Nicholls (ISBN number 0-13-185671-5). Anexcerpt from this publication is available in the Information Management Softwarefor z/OS Solutions Information Center.

IBM offers a wide variety of classroom and self-study courses to help you learnIMS. For a complete list of courses available, go to the IMS home page atwww.ibm.com/ims and link to the Training and Certification page.

IMS function names used in this information

In this information, the term HALDB Online Reorganization refers to theintegrated HALDB Online Reorganization function that is part of IMS Version 11,unless otherwise indicated.

Copyright IBM Corp. 1974, 2010 ix

http://publib.boulder.ibm.com/infocenter/imzichttp://publib.boulder.ibm.com/infocenter/imzichttp://publib.boulder.ibm.com/infocenter/imzichttp://publib.boulder.ibm.com/infocenter/imzichttp://www.ibm.com/software/data/ims/

IMS provides an integrated IMS Connect function, which offers a functionalreplacement for the IMS Connect tool (program number 5655-K52). In thisinformation, the term IMS Connect refers to the integrated IMS Connect functionthat is part of IMS Version 11, unless otherwise indicated.

How to read syntax diagrams

The following rules apply to the syntax diagrams that are used in this information:v Read the syntax diagrams from left to right, from top to bottom, following the

path of the line. The following conventions are used: The >>--- symbol indicates the beginning of a syntax diagram. The ---> symbol indicates that the syntax diagram is continued on the next

line. The >--- symbol indicates that a syntax diagram is continued from the

previous line. The --->< symbol indicates the end of a syntax diagram.

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

required_item

v Optional items appear below the main path.

required_itemoptional_item

If an optional item appears above the main path, that item has no effect on theexecution of the syntax element and is used only for readability.

optional_item

required_item

v If you can choose from two or more items, they appear vertically, in a stack.If you must choose one of the items, one item of the stack appears on the mainpath.

required_item required_choice1required_choice2

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

required_itemoptional_choice1optional_choice2

If one of the items is the default, it appears above the main path, and theremaining choices are shown below.

x Application Programming

required_itemdefault_choice

optional_choiceoptional_choice

v An arrow returning to the left, above the main line, indicates an item that can berepeated.

required_item repeatable_item

If the repeat arrow contains a comma, you must separate repeated items with acomma.

required_item

,

repeatable_item

A repeat arrow above a stack indicates that you can repeat the items in thestack.

v Sometimes a diagram must be split into fragments. The syntax fragment isshown separately from the main syntax diagram, but the contents of thefragment should be read as if they are on the main path of the diagram.

required_item fragment-name

fragment-name:

required_itemoptional_item

v In IMS, a b symbol indicates one blank position.v Keywords, and their minimum abbreviations if applicable, appear in uppercase.

They must be spelled exactly as shown. Variables appear in all lowercase italicletters (for example, column-name). They represent user-supplied names orvalues.

v Separate keywords and parameters by at least one space if no interveningpunctuation is shown in the diagram.

v Enter punctuation marks, parentheses, arithmetic operators, and other symbols,exactly as shown in the diagram.

v Footnotes are shown by a number in parentheses, for example (1).

Accessibility features for IMS Version 11

Accessibility features help a user who has a physical disability, such as restrictedmobility or limited vision, to use information technology products successfully.

Accessibility features

The following list includes the major accessibility features in z/OS products,including IMS Version 11. These features support:

About this information xi

v Keyboard-only operation.v Interfaces that are commonly used by screen readers and screen magnifiers.v Customization of display attributes such as color, contrast, and font size.

Note: The Information Management Software for z/OS Solutions InformationCenter (which includes information for IMS Version 11) and its related publicationsare accessibility-enabled for the IBM Home Page Reader. You can operate allfeatures by using the keyboard instead of the mouse.

Keyboard navigation

You can access IMS Version 11 ISPF panel functions by using a keyboard orkeyboard shortcut keys.

For information about navigating the IMS Version 11 ISPF panels using TSO/E orISPF, refer to the z/OS V1R8 TSO/E Primer, the z/OS V1R5 TSO/E User's Guide, andthe z/OS V1R9 ISPF User's Guide Volume 1. These guides describe how to navigateeach interface, including the use of keyboard shortcuts or function keys (PF keys).Each guide includes the default settings for the PF keys and explains how tomodify their functions.

Related accessibility information

Online documentation for IMS Version 11 is available in the InformationManagement Software for z/OS Solutions Information Center.

IBM and accessibility

See the IBM Accessibility Center at www.ibm.com/able for more information aboutthe commitment that IBM has to accessibility.

How to send your comments

Your feedback is important in helping us provide the most accurate and highestquality information. If you have any comments about this or any other IMSinformation, you can take one of the following actions:v From any topic in the information center at http://publib.boulder.ibm.com/

infocenter/imzic, click the Feedback link at the bottom of the topic andcomplete the Feedback form.

v Send your comments by e-mail to [email protected]. Be sure to include thetitle, the part number of the title, the version of IMS, and, if applicable, thespecific location of the text on which you are commenting (for example, a pagenumber in the PDF or a heading in the information center).

xii Application Programming

http://www.ibm.com/ablehttp://publib.boulder.ibm.com/infocenter/imzichttp://publib.boulder.ibm.com/infocenter/imzic

Changes to the IMS library

Changes to the IMS library for IMS Version 11 include minor title changes to allthe publications, merging four sets of publications, a change to how IMS Messagesand Codes are delivered, and a change to the number of formats in which theinformation is provided.

The titles of all PDF publications in the IMS Version 11 library have been changedso that the publication titles match the contents view (navigation tree) titles in theinformation center. For example, the IMS Diagnosis Guide has been renamed to IMSDiagnosis. In addition, the titles for the three IMS Command Reference PDF volumeshave been renamed so that their titles better reflect the contents of eachpublication, as follows:v IMS Version 11 Commands, Volume 1: IMS Commands A-Mv IMS Version 11 Commands, Volume 2: IMS Commands N-Vv IMS Version 11 Commands, Volume 3: IMS Component and z/OS Commands

Four sets of publications have been streamlined so that information is grouped in amore intuitive, retrievable organization:v To eliminate redundancy and group relevant application programming planning

information with associated application programming tasks, the IMS ApplicationProgramming Planning Guide has been merged with the IMS ApplicationProgramming Guide, in a new title: IMS Version 11 Application Programming.

v To group diagnosis reference information with associated diagnosis tasks, theIMS Diagnosis Reference has been merged with the IMS Diagnosis Guide, in a newtitle: IMS Version 11 Diagnosis.

v To group all system administration tasks, regardless of whether the tasks relateto using a single IMS or an IMSplex, the IMS IMSplex Administration Guide hasbeen merged with the IMS System Administration Guide, in a new title: IMSVersion 11 System Administration.

v To group system definition reference information with associated systemdefinition tasks, the IMS System Definition Reference has been merged with theIMS System Definition Guide, in a new title: IMS Version 11 System Definition.

IBM's strategy is to deliver product information in Web-based information centers.Therefore, the IMS Version 11 information is optimized for viewing in theinformation center (which also includes PDF versions of books) and, except formessages and codes, is not provided in BookManager format. Information centersprovide many advantages over PDF and BookManager formats, including:v Improved retrievability: Users can search across the entire information center, or

set filters to search categories of information (for example, search only IMSVersion 11 information, or search only IMS Version 10 information). Users canalso search for information center content by using a search engine such asGoogle, or from www.ibm.com.

v Improved information currency: Users can subscribe to information updates byusing RSS feeds.

v Accessibility support.v Multi-language support.

Copyright IBM Corp. 1974, 2010 xiii

|

|

||||

||||||

|

|

|

||

||||

|||

||||

|||

|||||

|||||

||

|

|

Beginning with IMS Version 10, the four volumes of IMS Messages and Codesinclude messages and codes from IMS Version 10 and all later versions. Individualmessages and codes will include version-specific changes, if applicable. Because thesame messages and codes volumes support IMS Version 10 and later, thosevolumes will continue to be available in BookManager format.

The following figure illustrates how the IMS Version 11 library is organized in theinformation center, which is available at http://publib.boulder.ibm.com/infocenter/imzic.

xiv Application Programming

|||||

||||

http://publib.boulder.ibm.com/infocenter/imzichttp://publib.boulder.ibm.com/infocenter/imzic

The following table describes high-level user tasks (navigation tree category) andthe IMS Version 11 publications that support those tasks.

Installing IMSProgram directory

InstallationSystem definition

Communications and connectionsDatabase administration

Operations and automationSystem administration

IMS administration

Searching for messages and codesDiagnosis

IMS messages and codesIRLM messages and codes

Troubleshootingfor IMS

{=Application programming

Application programming APIsSystem programming APIs

Programmingfor IMS

Release planningRelease planningfor IMS

IMS glossaryIndex for IMSVersion 11

IMS commandsExit routines

Database utilitiesSystem utilities

IMS referenceinformation

Changes to the IMS library for IMS Version 11Licensed Program Specifications

Fact sheetIntroduction to IMS

IMS overview

Figure 1. Organization of the IMS Version 11 library in the information center

Changes to the IMS library xv

|

|||||

Table 1. High-level user tasks and the IMS Version 11 publications that supports those tasks

Task(navigation treecategory)

In the InformationCenter Contents PDF

IMS overview IMS Version 11 LicensedProgram Specifications

Summarizes the functions and capabilities of IMS, listshardware and software requirements, and provides licensingand warranty details.

PDF

IMS Version 11 Fact Sheet Provides an overview of the IMS Version 11 features. PDF

An Introduction to IMS:Your Complete Guide toIBM's InformationManagement System

Provides the first five chapters of a retail publication thatintroduces the IMS product and its features.

Releaseplanning forIMS

IMS Version 11 ReleasePlanning

These topics provide general information to help youevaluate and plan for IMS Version 11. The topics describe thenew features and enhancements for IMS Version 11, thehardware and software requirements for these new featuresand enhancements, considerations for migration andcoexistence for IMS Version 11, and an overview of the IMSTools that are enhanced to work with IMS Version 11.

PDF

Installing IMS Program Directory forInformation ManagementSystem Transaction andDatabase Servers

Provides information about the material and procedures thatare associated with the installation of IMS Version 11.

PDF

IMS Version 11Installation

These topics provide guidance information for preparing foran IMS installation process and running the IMS installationverification program (IVP). The topics also describe thesample applications that are provided with IMS.

PDF

IMS Version 11 SystemDefinition

These topics provide guidance information for designing anIMS system, including information about defining andtailoring the IMS system, IMS Common Queue Server (CQS),IMS Common Service Layer (CSL), integrated IMS Connect,and IMS Transport Manager Subsystem (TMS). The topicsalso include descriptions of the IMS macros, procedures, andmembers of the IMS PROCLIB data set.

PDF

xvi Application Programming

||

|||||||

||||||

|

|||

||||

|||

|||

|||||||||

|

|||||

|||

||||||

|

|||||||||

|

http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/ims_lpshome.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/ims_lpshome.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.lps/dfslpsi1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.fact/factsheet_v11.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.fact/Fact Sheet_v11_proof2.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsintro.doc.intro/intro.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsintro.doc.intro/intro.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsintro.doc.intro/intro.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsintro.doc.intro/intro.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.rpg/rpg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.rpg/rpg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.rpg/dfsrpgi2.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/ims_progdir.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/ims_progdir.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/ims_progdir.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/ims_progdir.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/i1087881.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.ins/ins.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.ins/ins.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.ins/dfsinsi1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sdg/ims_sdg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sdg/ims_sdg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sdg/dfssdgi1.pdf?noframes=true

Table 1. High-level user tasks and the IMS Version 11 publications that supports those tasks (continued)



IMSadministration

IMS Version 11Communications andConnections

These topics describe how to administer IMScommunications and connections: CPI Communications andAPPC/IMS, facilities for attaching to external subsystems,IMS Extended Terminal Option (ETO), IMS Connect, IMSUniversal driver connections, Multiple Systems Coupling(MSC), IMS Open Database Access (ODBA) and databaseresource adapter (DRA) interfaces, IMS Open TransactionManager Access (OTMA), SLU P and Financecommunication systems, TCP/IP communications, andVTAM networking.

PDF

IMS Version 11 DatabaseAdministration

These topics describe IMS database types and concepts, andalso describe how to design, implement, maintain, modify,back up, and recover IMS databases.

PDF

IMS Version 11Operations andAutomation

These topics provide guidance information for selecting toolsand options for operating an IMS system, for recovering anIMS system, and for automating IMS operations andrecovery tasks. The topics also describe how to developprocedures for the master terminal operator and the enduser.

PDF

IMS Version 11 SystemAdministration

These topics provide guidance information for managing theadministration and operations of a single IMS or one ormore IMS systems that work as a unit (an IMSplex). Thetopics describe designing, documenting, operating,maintaining, and recovering an IMS system, as well as theDatabase Recovery Control (DBRC) facility, Remote SiteRecovery (RSR), and the Extended Recovery Facility (XRF).The topics also include conceptual information about theIMS Base Primitive Environment (BPE), IMS CommonQueue Server (CQS), and IMS Common Service Layer (CSL),all of which can be part of an IMSplex, as well as taskinformation for sharing data and message queues in anIMSplex.

PDF

Changes to the IMS library xvii

|

|||||||

|||||

||||||||||

|

|||||

|

|||

||||||

|

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

|

http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.ccg/ccg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.ccg/ccg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.ccg/ccg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.ccg/dfsccgi1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.dag/dag.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.dag/dag.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.dag/dfsdagi1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.oag/oag.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.oag/oag.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.oag/oag.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.oag/dfsoagi1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sag/sagintro/sag.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sag/sagintro/sag.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sag/dfssagi1.pdf?noframes=true




Programmingfor IMS

IMS Version 11Application Programming

These topics provide guidance information for writingapplication programs that access IMS databases or IMStransactions. The topics describe how to gather and analyzeprogram requirements, and how to develop and debug IMSapplication programs. They also describe how to usedifferent programming languages to issue DL/I calls, andinclude information about the IMS solutions for Javadevelopment. They also describe how to use differentprogramming languages to issue EXEC DL/I calls.Application programming interface (API) information is inIMS Version 11 Application Programming APIs.

PDF

IMS Version 11Application ProgrammingAPIs

These topics provide reference information for the IMSapplication programming interfaces (APIs), including DL/I,EXEC DL/I, the classic Java APIs for IMS, the IMS Universaldrivers, and the Java dependent region resource adapter. Thetopics also provide reference information for the IMSAdapter for REXX, the DL/I test program (DFSDDLT0), andthe IMS Message Format Service (MFS). Guidanceinformation for writing IMS application programs is in IMSVersion 11 Application Programming.

PDF

IMS Version 11 SystemProgramming APIs

These topics provide reference information for IMS systemapplication programming interface (API) calls for IMSCommon Queue Server (CQS); IMS Common Service Layer(CSL); IMS data propagation with IMS DataPropagator forz/OS; IMS Database Resource Adapter (DRA); and the IMSDatabase Recovery Control (DBRC) facility.

PDF

xviii Application Programming

|

|||||||

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

|

|||

|||||||||

|

||||||||

|

http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.apg/apg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.apg/apg.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.apg/dfsapgi1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.apr/apr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.apr/apr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.apr/apr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.apr/dfsapri1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.spr/spr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.spr/spr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.spr/dfsspri1.pdf?noframes=true




Troubleshootingfor IMS

IMS Version 11 Diagnosis These topics provide guidance and reference information forsetting up an IMS system for diagnosis, collectinginformation to help diagnose IMS problems, and searchingproblem-reporting databases, such as the IBM ElectronicIncident Submission (EIS) Web site. These topics alsodescribe how to use keywords to develop a failuredescription that you can use to search problem-reportingdatabases and communicate with IBM Software Support.

PDF

IMS Messages and Codes,Volume 1: DFS Messages

These topics provide reference information for the IMSmessages that have the DFS prefix, along with theirassociated return codes. The topics also provide diagnosticinformation that helps programmers, operators, andsystem-support personnel diagnose problems in IMS. IMSmessages with other prefixes are in IMS Messages and Codes,Volume 2: Non-DFS Messages.

PDF

IMS Messages and Codes,Volume 2: Non-DFSMessages

These topics provide reference information fornon-DFS-prefixed IMS messages that are associated with IMSBase Primitive Environment (BPE); IMS Common QueueServer (CQS); IMS Common Service Layer (CSL); DatabaseRecovery Control (DBRC); and integrated IMS Connect. Thetopics also provide diagnostic reference information thathelps programmers, operators, and system-supportpersonnel diagnose problems in IMS. IMS messages thathave the DFS prefix are in IMS Messages and Codes, Volume 1:DFS Messages.

PDF

IMS Messages and Codes,Volume 3: IMS AbendCodes

These topics provide reference information for all IMSabnormal termination (abend) codes, including analysis,explanation, possible causes, and APAR processinginstructions.

PDF

IMS Messages and Codes,Volume 4: IMSComponent Codes

These topics provide return, reason, sense, function, andstatus codes for IMS Base Primitive Environment (BPE); IMSCommon Queue Server (CQS); IMS Common Service Layer(CSL); Database Recovery Control (DBRC) facility; andintegrated IMS Connect. The topics also provide diagnosticreference information that helps programmers, operators,and system-support personnel diagnose problems in IMS.IMS abend codes are in IMS Messages and Codes, Volume 3:IMS Abend Codes.

PDF

IRLM Messages andCodes for IMS and DB2

for z/OS

These topics describe the IRLM messages and codes issuedby the internal resource lock manager (IRLM) to IMS.

PDF

Changes to the IMS library xix

|

|||||||

|||||||||||

|

|||||||||

|

|||

||||||||||

|

|||

||||

|

|||

|||||||||

|

|||

|||

http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.dgr/dgr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.dgr/dfsdg1i1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/dfsmc1h4.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/dfsmc2h4.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/dfsmc3h4.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/common/mc.htmlhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.imsmsgs.doc.msgs/dfsmc4h4.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.irlm.doc/irlm_main.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.irlm.doc/irlm_main.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.irlm.doc/irlm_main.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.irlm.doc/dxrmc002.pdf?noframes=true




IMS referenceinformation

IMS Version 11Commands, Volume 1:IMS Commands A-M

These topics provide command syntax and usageinformation for the IMS type-1 and type-2 commands/ACTIVATE through /MSVERIFY. The topics also describethe IMS command language and how to send commands toIMS in different environments. Information about allnon-type-1 and non-type-2 IMS commands is in IMS Version11 Commands, Volume 3: IMS Component and z/OS Commands.

PDF

IMS Version 11Commands, Volume 2:IMS Commands N-V

These topics provide command syntax and usageinformation for the IMS type-1 and type-2 commands/NRESTART through /VUNLOAD. The topics also describethe IMS command language and how to send commands toIMS in different environments. Information about allnon-type-1 and non-type-2 IMS commands is in IMS Version11 Commands, Volume 3: IMS Component and z/OS Commands.

PDF

IMS Version 11Commands, Volume 3:IMS Component and z/OSCommands

These topics provide command syntax and usageinformation for the following types of IMS commands: BasePrimitive Environment (BPE); Common Service Layer (CSL);Database Recovery Control (DBRC) facility; IMS TransportManager Subsystem (TMS); integrated IMS Connect; and thez/OS commands for IMS. Information about IMS type-1 andtype-2 commands is in IMS Version 11 Commands, Volume 1:IMS Commands A-M and IMS Version 11 Commands,Volume 2: IMS Commands N-V.

PDF

IMS Version 11 ExitRoutines

These topics provide reference information for the exitroutines that you can use to customize IMS database,system, transaction management, IMSplex, Base PrimitiveEnvironment (BPE), Common Queue Server (CQS), andintegrated IMS Connect environments.

PDF

IMS Version 11 DatabaseUtilities

These topics provide reference information for the utilitiesthat you can use to migrate, reorganize, and recover adatabase.

PDF

IMS Version 11 SystemUtilities

These topics provide reference information for the utilitiesthat you can use with the IMS system to generate IMSresources, analyze IMS activity, manage IMS logging, run theIMS Database Recovery Control (DBRC) facility, maintainIMS networking services, convert Security Maintenanceutility (SMU) source, and maintain the resource definitiondata sets (RDDSs).

PDF

IMS Version 11 MasterIndex and Glossary

Provides a central index for all the IMS Version 11information, as well as a glossary of IMS terms. Althoughthe combined IMS Version 11 Master Index and Glossary isavailable in PDF format, the index does not include links.The IMS master index is included in the information centerunder IMS Version 11 Index for IMS Version 11. Theinformation center master index provides live links to topics.The IMS glossary is included in the information center underIMS Version 11 IMS glossary.

PDF

xx Application Programming

|

|||||||

|||||

|||||||

|

|||

|||||||

|

||||

|||||||||

|

|||||||

|

|||||

|

|||||||||

|

|||||||||||

|

|

http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/dfscr1i1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/dfscr2i1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/imscmdsintro/cr.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.cr/dfscr3i1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.err/err.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.err/err.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.err/dfserri1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.dur/dur.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.dur/dur.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.dur/dfsduri1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sur/sur.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sur/sur.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc.sur/dfssuri1.pdf?noframes=truehttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/mindexa.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/mindexa.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims.glossary.doc/ims_glossary.htmhttp://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims11.doc/dfsmigi1.pdf?noframes=true

Part 1. Application programming design

To design an application program for IMS, you need to identify the applicationdata and analyze requirements for application processing. You may also need toperform other tasks, such as gathering requirements for database and messageprocessing options, and testing an application program.

Copyright IBM Corp. 1974, 2010 1

|

2 Application Programming

Chapter 1. Designing an application: Introductory concepts

This section provides an introduction to designing application programs. Itexplains some basic concepts about processing a database, and gives an overviewof the tasks covered in this information.

Storing and processing information in a databaseThe advantages of storing and processing data in a database are that all of the dataneeds to appear only once and that each program must process only the data thatit needs.

One way to understand this is to compare three ways of storing data: in separatefiles, in a combined file, and in a database.

Storing data in separate files

If you keep separate files of data for each part of your organization, you canensure that each program uses only the data it needs, but you must store a lot ofdata in multiple places simultaneously. Problems with keeping separate files are:v Redundant data takes up space that could be put to better usev Maintaining separate files can be difficult and complex

For example, suppose that a medical clinic keeps separate files for each of itsdepartments, such as the clinic department, the accounting department, and theophthalmology department:v The clinic department keeps data about each patient who visits the clinic, such

as:Identification numberNameAddressIllnessesDate of each illnessDate patient came to clinic for treatmentTreatment given for each illnessDoctor that prescribed treatmentCharge for treatment

v The accounting department also keeps information about each patient. Theinformation that the accounting department might keep for each patient is:

Identification numberNameAddressCharge for treatmentAmount of payments

v The information that the ophthalmology department might keep for each patientis:

Identification number

Copyright IBM Corp. 1974, 2010 3

NameAddressIllnesses relating to ophthalmologyDate of each illnessNames of members in patient's householdRelationship between patient and each household member

If each of these departments keeps separate files, each department uses only thedata that it needs, but much of the data is redundant. For example, everydepartment in the clinic uses at least the patient's number, name, and address.Updating the data is also a problem, because if a department changes a piece ofdata, the same data must be updated in each separate file. Therefore, it is difficultto keep the data in each department's files current. Current data might exist in onefile while defunct data remains in another file.

Storing data in a combined file

Another way to store data is to combine all the files into one file for alldepartments to use. In the medical example, the patient record that would be usedby each department would contain these fields:

Identification numberNameAddressIllnessesDate of each illnessDate patient came to clinic for treatmentTreatment given for each illnessDoctor that prescribed treatmentCharge for treatmentAmount of paymentsNames of members in patient's householdRelationship between patient and each household member

Using a combined file solves the updating problem, because all the data is in oneplace, but it creates a new problem: the programs that process this data mustaccess the entire file record to get to the part that they need. For example, toprocess only the patient's number, charges, and payments, an accounting programmust access all of the other fields also. In addition, changing the format of any ofthe fields within the patient's record affects all the application programs, not justthe programs that use that field.

Using combined files can also involve security risks, because all of the programshave access to all of the fields in a record.

Storing data in a database

Storing data in a database gives you the advantages of both separate files andcombined files: all the data appears only once, and each program has access to thedata that it needs. This means that:v When you update a field, you do it in one place only.


v Because you store each piece of information only in one place, you cannot havean updated version of the information in one place and an out-of-date version inanother place.

v Each program accesses only the data it needs.v You can prevent programs from accessing private or secured information.

In addition, storing data in a database has two advantages that neither of the otherways has:v If you change the format of part of a database record, the change does not affect

the programs that do not use the changed information.v Programs are not affected by how the data is stored.

Because the program is independent of the physical data, a database can store allthe data only once and yet make it possible for each program to use only the datathat it needs. In a database, what the data looks like when it is stored is differentfrom what it looks like to an application program.

Database hierarchy examplesIn an IMS DB, a record is stored and accessed in a hierarchy. A hierarchy showshow each piece of data in a record relates to other pieces of data in the record.

IMS connects the pieces of information in a database record by defining therelationships between the pieces of information that relate to the same subject. Theresult is a database hierarchy.

Medical hierarchy example

The medical database shown in following figure contains information that amedical clinic keeps about its patients. The hierarchies used in the medicalhierarchy example are used with full-function databases and Fast Path data entrydatabases (DEDBs).

Each piece of data represented in the figure above is called a segment in thehierarchy. Each segment contains one or more fields of information. The PATIENTsegment, for example, contains all the information that relates strictly to thepatient: the patient's identification number, name, and address.

Definitions: A segment is the smallest unit of data that an application program canretrieve from the database. A field is the smallest unit of a segment.

The PATIENT segment in the medical database is the root segment. The segmentsbelow the root segment are the dependents, or children, of the root. For example,

Figure 2. Medical hierarchy

Chapter 1. Designing an application: Introductory concepts 5

ILLNESS, BILLING, and HOUSHOLD are all children of PATIENT. ILLNESS,BILLING, and HOUSHOLD are called direct dependents of PATIENT; TREATMNTand PAYMENT are also dependents of PATIENT, but they are not directdependents, because they are at a lower level in the hierarchy.

A database record is a single root segment (root segment occurrence) and all of itsdependents. In the medical example, a database record is all of the informationabout one patient.

Definitions: A root segment is the highest-level segment. A dependent is a segmentbelow a root segment. A root segment occurrence is a database record and all of itsdependents.

Each database record has only one root segment occurrence, but it might haveseveral occurrences at lower levels. For example, the database record for a patientcontains only one occurrence of the PATIENT segment type, but it might containseveral ILLNESS and TREATMNT segment occurrences for that patient.

The tables that follow show the layouts of each segment in the hierarchy.

The segments field names are in the first row of each table. The number beloweach field name is the length in bytes that has been defined for that field.v PATIENT Segment

The following table shows the PATIENT segment.It has three fields: The patients number (PATNO) The patients name (NAME) The patient's address (ADDR)PATIENT has a unique key field: PATNO. PATIENT segments are stored inascending order based on the patient number. The lowest patient number in thedatabase is 00001 and the highest is 10500.

Table 2. PATIENT segment

Field name Field length

PATNO 10

NAME 5

ADDR 30

v ILLNESS SegmentThe following figure shows the ILLNESS segment.It has two fields: The date when the patient came to the clinic with the illness (ILLDATE) The name of the illness (ILLNAME)The key field is ILLDATE. Because it is possible for a patient to come to theclinic with more than one illness on the same date, this key field is non-unique,that is, there may be more than one ILLNESS segment with the same (an equal)key field value.Usually during installation, the database administrator (DBA) decides the orderin which to place the database segments with equal or no keys. The DBA canuse the RULES keyword of the SEGM statement of the DBD to specify the orderof the segments.


For segments with equal keys or no keys, RULES determines where the segmentis inserted. Where RULES=LAST, ILLNESS segments that have equal keys arestored on a first-in-first-out basis among those with equal keys. ILLNESSsegments with unique keys are stored in ascending order on the date field,regardless of RULES. ILLDATE is specified in the format YYYYMMDD.

Table 3. ILLNESS segment


ILLDATE 8

ILLNAME 10

v TREATMNT SegmentThe following table shows the TREATMNT segment.It contains four fields: The date of the treatment (DATE) The medicine that was given to the patient (MEDICINE) The quantity of the medicine that the patient received (QUANTITY) The name of the doctor who prescribed the treatment (DOCTOR)The TREATMNT segments key field is DATE. Because a patient may receivemore than one treatment on the same date, DATE is a non-unique key field.TREATMNT, like ILLNESS, has been specified as having RULES=LAST.TREATMNT segments are also stored on a first-in-first-out basis. DATE isspecified in the same format as ILLDATEYYYYMMDD.

Table 4. TREATMNT segment


DATE 8

MEDICINE 10

QUANTITY 4

DOCTOR 10

v BILLING SegmentThe following table shows the BILLING segment. It has only one field: theamount of the current bill. BILLING has no key field.

Table 5. BILLING segment


BILLING 6

v PAYMENT SegmentThe following table shows the PAYMENT segment. It has only one field: theamount of payments for the month. The PAYMENT segment has no key field.

Table 6. PAYMENT segment


PAYMENT 6

v HOUSHOLD SegmentThe following table shows the HOUSHOLD segment.It contains two fields:


The names of the members of the patient's household (RELNAME) How each member of the household is related to the patient (RELATN)The HOUSHOLD segments key field is RELNAME.

Table 7. HOUSHOLD segment


RELNAME 10

RELATN 8

Bank account hierarchy example

The bank account hierarchy is an example of an application program that is usedwith main storage databases (MSDBs). In the medical hierarchy example, thedatabase record for a particular patient comprises the PATIENT segment and all ofthe segments underneath the PATIENT segment. In an MSDB, such as the one inthe bank account example, the segment is the whole database record. The databaserecord contains only the fields that the segment contains.

The two types of MSDBs are related and nonrelated. In related MSDBs, each segmentis owned by one logical terminal. The "owned" segment can only be updated bythe terminal that owns it. In nonrelated MSDBs, the segments are not owned bylogical terminals. The following examples of a related MSDB and a nonrelatedMSDB illustrate the differences between the two types of databases.

Related MSDBs

Related MSDBs can be fixed or dynamic. In a fixed related MSDB, you can storesummary data about a particular teller at a bank. For example, you can have anidentification code for the teller's terminal. Then you can keep a count of thatteller's transactions and balance for the day. This type of application requires asegment with three fields:

TELLERIDA two-character code that identifies the teller

TRANCNTThe number of transactions the teller has processed

TELLBALThe balance for the teller

The following table shows what the segment for this type of application programlooks like.

Table 8. Teller segment in a fixed related MSDB

TELLERID TRANCNT TELLBAL

Some of the characteristics of fixed related MSDBs include:v You can only read and replace segments. You cannot delete or insert segments.

In the bank teller example, the teller can change the number of transactionsprocessed, but you cannot add or delete any segments. You never need to add ordelete segments.

v Each segment is assigned to one logical terminal. Only the owning terminal canchange a segment, but other terminals can read the segment. In the bank teller


example, you do not want tellers to update the information about other tellers,but you allow the tellers to view each others information. Tellers are responsiblefor their own transactions.

v The name of the logical terminal that owns the segment is the segment's key.Unlike non-MSDB segments, the MSDB key is not a field of the segment. It isused as a means of storing and accessing segments.

v A logical terminal can only own one segment in any one MSDB.

In a dynamic related MSDB, you can store data summarizing the activity of allbank tellers at a single branch. For example, this segment contains:

BRANCHNOThe identification number for the branch

TOTALThe bank branch's current balance

TRANCNTThe number of transactions for the branch on that day

DEPBALThe deposit balance, giving the total dollar amount of deposits for thebranch

WTHBALThe withdrawal balance, giving the dollar amount of the withdrawals forthe branch

The following table shows what the branch summary segment looks like in adynamic related MSDB.

Table 9. Branch summary segment in a dynamic related MSDB

BRANCHNO TOTAL TRANCNT DEPBAL WTHBAL

How dynamic related MSDBs differ from fixed related MSDBs:v The owning logical terminal can delete and insert segments in a dynamic related

MSDB.v The MSDB can have a pool of unassigned segments. This kind of segment is

assigned to a logical terminal when the logical terminal inserts it, and isreturned to the pool when the logical terminal deletes it.

Nonrelated MSDBs

A nonrelated MSDB is used to store data that is updated by several terminalsduring the same time period. For example, you might store data about anindividuals' bank accounts in a nonrelated MSDB segment, so that the informationcan be updated by a teller at any terminal. Your program might need to access thedata in the following segment fields:

ACCNTNOThe account number

BRANCHThe name of the branch where the account is

TRANCNTThe number of transactions for this account this month


BALANCEThe current balance

The following table shows what the account segment in a nonrelated MSDBapplication program looks like.

Table 10. Account segment in a nonrelated MSDB

ACCNTNO BRANCH TRANCNT BALANCE

The characteristics of nonrelated MSDBs include:v Segments are not owned by terminals as they are in related MSDBs. Therefore,

IMS programs and Fast Path programs can update these segments. Updatingsegments is not restricted to the owning logical terminal.

v Your program cannot delete or insert segments.v Segment keys can be the name of a logical terminal. A nonrelated MSDB exists

with terminal-related keys. The segments are not owned by the logical terminals,and the logical terminal name is used to identify the segment.

v If the key is not the name of a logical terminal, it can be any value, and it is inthe first field of the segment. Segments are loaded in key sequence.

Your program's view of the dataIMS uses two kinds of control blocks to enable application programs to beindependent of your method of storing data in the database, the databasedescription (DBD), and the database program communication block (DB PCB).

Database Description (DBD)

A database description (DBD) is physical structure of the database. The DBD alsodefines the appearance and contents, or fields, that make up each of the segmenttypes in the database.

For example, the DBD for the medical database hierarchy shown in Medicalhierarchy example describes the physical structure of the hierarchy and each ofthe six segment types in the hierarchy: PATIENT, ILLNESS, TREATMNT, BILLING,PAYMENT, and HOUSHOLD.

Related Reading: For more information on generating DBDs, see IMS Version 11Database Utilities.

Database Program Communication Block (DB PCB)

A database program communication block (DB PCB) is a control block that defines anapplication program's view of the database. An application program often needs toprocess only some of the segments in a database. A PCB defines which of thesegments in the database the program is allowed to accesswhich segments theprogram is sensitive to.

The data structures that are available to the program contain only segments thatthe program is sensitive to. The PCB also defines how the application program isallowed to process the segments in the data structure: whether the program canonly read the segments, or whether it can also update them.


To obtain the highest level of data availability, your PCBs should request thefewest number of sensitive segments and the least capability needed to completethe task.

All the DB PCBs for a single application program are contained in a programspecification block (PSB). A program might use only one DB PCB (if it processes onlyone data structure) or it might use several DB PCBs, one for each data structure.

Related Reading: For more information on generating PSBs, see IMS Version 11Database Utilities.

The following figure illustrates the concept of defining a view for an applicationprogram. An accounting program that calculates and prints bills for the clinic'spatients would need only the PATIENT, BILLING, and PAYMENT segments. Youcould define the data structure shown in the following figure in a DB PCB for thisprogram.

A program that updates the database with information on patients' illnesses andtreatments, in contrast, would need to process the PATIENT, ILLNESS, andTREATMNT segments. You could define the data structure shown in the followingfigure in a DB PCB for this program.

Figure 3. Accounting program's view of the database


Sometimes a program needs to process all of the segments in the database. Whenthis is true, the program's view of the database as defined in the DB PCB is thesame as the database hierarchy that is defined in the DBD.

An application program processes only the segments in a database that it requires;therefore, if you change the format of a segment that is not processed, you do notchange the program. A program is affected only by the segments that it accesses. Inaddition to being sensitive to only certain segments in a database, a program canalso be sensitive to only certain fields within a segment. If you change a segmentor field that the program is not sensitive to, it does not affect the program. Youdefine segment and field-level sensitivity during PSBGEN.

Definition: Field-level sensitivity is when a program is sensitive to only certainfields within a segment.

Related Reading: For more information, see IMS Version 11 Database Administration.

Processing a database recordTo process the information in the database, your application programcommunicates with IMS in three ways: by passing control, by communicatingprocessing requests, and by exchanging information using DL/I calls.v Passing controlIMS passes control to your application program through an

entry statement in your program. Your program returns control to IMS when ithas finished its processing.When you are running a CICS online program, CICS passes control to yourapplication program, and your program schedules a PSB to make IMS requests.Your program returns control to CICS. If you are running a batch or BMPprogram, IMS passes control to your program with an existing PSB scheduled.

v Communicating processing requestsYou communicate processing requests toIMS in one of two ways: In IMS, you issue DL/I calls to process the database. In CICS, you can issue either DL/I calls or EXEC DLI commands. EXEC DLI

commands more closely resemble a higher-level language than do DL/I calls.

PATIENT

TREATMNT

ILLNESS

Figure 4. Patient illness program's view of the database


v Exchanging information using DL/I callsYour program exchanges informationin two areas: A DL/I call reports the results of your request in a control block and the AIB

communication block when using one of the AIB interfaces. For programswritten using DL/I calls, this control block is the DB PCB. For programswritten using EXEC DLI commands, this control block is the DLI interfaceblock (DIB). The contents of the DIB reflect the status of the last DL/Icommand executed in the program. Your program includes a mask of theappropriate control block and uses this mask to check the results of therequest.

When you request a segment from the database, IMS returns the segment toyour I/O area. When you want to update a segment in the database, youplace the new value of the segment in the I/O area.

An application program can read and update a database. When you update adatabase, you can replace, delete, or add segments. In IMS, you indicate in theDL/I call the segment you want to process, and whether you want to read orupdate it. In CICS, you can indicate what you want using either a DL/I call or anEXEC DLI command.

Tasks for developing an applicationThe following tasks are involved in developing an IMS application, and theprograms that are part of the application.

Designing the application

Application program design varies from place to place, and from one applicationto another.

Therefore, this information does not try to cover the early tasks that are part ofdesigning an application program. Instead, it covers only the tasks that you areconcerned with after the early specifications for the application have beendeveloped. The tasks for designing the application are:v Analyzing Application Data Requirements

Two important parts of application design are defining the data that each of thebusiness processes in the application requires and designing a local view foreach of the business processes.

v Analyzing Application Processing RequirementsWhen you understand the business processes that are part of the application,you can analyze the requirements of each business process in terms of theprocessing that is available with different types of application programs.

v Gathering Requirements for Database OptionsYou then need to look at the database options that can most efficiently meet therequirements, and gather information about your application's data requirementsthat relates to each of the options.

v Gathering Requirements for Message Processing OptionsIf your application communicates with terminals and other applicationprograms, look at the message processing options and the requirements theysatisfy.

For more information about designing a CICS application, see CICS TransactionServer for z/OS V3.2 CICS Application Programming Guide.


Developing specifications

Developing specifications involves defining what your application will do, andhow it will be done. The task of developing specifications is not described in thisinformation because it depends entirely on the specific application and yourstandards.

Implementing the design

When the specifications for each of the programs in the application are developed,you can structure and code the programs according to those specifications. Thetasks of implementing the design are:v Writing the Database Processing Part of the Program

When the program design is complete, you can structure and code your reques

IMS Version 11 -...

Documents

Transcript of IMS Version 11 -...